Puzzler PHP SDK

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

composer require tomgould/puzzlerphpsdk

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'],
]);