---
title: 'Puzzler PHP SDK'
canonical: 'https://www.dealmobile.co.uk/projects/puzzler-php-sdk'
url: 'https://www.dealmobile.co.uk/projects/puzzler-php-sdk'
type: Project
summary: 'A small PHP library for publishers who license puzzles from Puzzler Media. It signs each request, filters puzzles by date, type and name, and maps HTTP errors to exceptions.'
---

# Puzzler PHP SDK

An unofficial PHP client for the Puzzler Media puzzles API, with signed requests and clear errors.

![A terminal showing one signed request built by the Puzzler PHP SDK: the POST address, client ID, API key and timestamp headers, a highlighted signature and the JSON body.](https://www.dealmobile.co.uk/sites/default/files/styles/almanac_shot_md/public/content/images/products/puzzler-php-sdk-light.png.webp?itok=Aaie0P2V)

- **Kind:** Library
- **Status:** Maintained
- **Started:** 2025
- **Licence:** MIT
- **Stack:** PHP, cURL, Composer, PHPUnit, GitHub Actions, REST APIs
- **Links:** [Source on GitHub](https://github.com/tomgould/PuzzlerPHPSDK), [Package on Packagist](https://packagist.org/packages/tomgould/puzzlerphpsdk)

Puzzler Media supplies crosswords, sudoku, wordsearches and other puzzles to publishers through a REST API. The Puzzler PHP SDK is a small client for that API, for PHP developers who need to pull puzzles into a site or an archive. It isn’t affiliated with Puzzler Media, and you need your own client ID, API key and secret key from them.

## What it does

- Checks the API’s health.
- Fetches the dictionary of puzzle types and names in the latest bundle, such as `XW` for crosswords and `SU` for the easy, medium and hard sudoku.
- Collects puzzles, filtered by a date, a date range, puzzle types or exact puzzle names, alone or combined.
- Signs every request, with a fresh signature each time.
- Turns HTTP errors into specific exceptions: authentication (401), bad request (400), not found (404), method not allowed (405) and server errors (500 and 502). Each one carries the raw response body for debugging.

## How it’s built

The SDK needs PHP 7.4 or later with the cURL and JSON extensions, and nothing else. A `PuzzlerClient` gives you a puzzle client and a health client, which share one HTTP class.

That HTTP class sends the client ID and API key headers with a timestamp and a signature made from the secret key. Signatures are valid for five minutes, so the troubleshooting notes cover clock skew. The API has a quirk: with filters, the filters go straight into the request body, but with no filters the body must be `{"model": {}}`. The SDK handles that, so callers don’t need to know.

The cURL transport sits in a protected `send()` method. Tests replace it, so request signing and the mapping from status codes to exceptions are tested offline. A separate set of integration tests runs against the real API when credentials are set in the environment, and skips itself when they aren’t. GitHub Actions runs the tests on PHP 7.4 to 8.4.

The README also explains how the API behaves. It only serves the latest bundle of puzzles, so building an archive means fetching and storing puzzles on a schedule. And filtering by a puzzle name only works if that puzzle’s type isn’t in the types filter as well.

## How to use it

```bash
composer require tomgould/puzzlerphpsdk

```

```php
use TomGould\PuzzlerPHPSDK\PuzzlerClient;

$client = new PuzzlerClient('YOUR_CLIENT_ID', 'YOUR_API_KEY', 'YOUR_SECRET_KEY');

$wordsearches = $client->puzzle()->collect([
    'puzzleDate' => date('Y-m-d'),
    'puzzleTypes' => ['WS'],
]);

```

---

Index of this site: [llms.txt](https://www.dealmobile.co.uk/llms.txt)