README

A PHP wrapper for the PunkAPI — all 415 BrewDog DIY Dog recipes.

The original PunkAPI by Sam Mason is no longer online. This wrapper now defaults to the v3 API hosted by alxiw, and includes bundled offline data as a fallback so your code always gets results — even if the API is unreachable.

Requirements

PHP >= 8.3
Guzzle ^7.0 (installed automatically via Composer)

Installation

composer require billythekid/punk-api

Quick Start

use billythekid\PunkApi;

$punkApi = PunkApi::create();

// Get beers (hits the live API, falls back to local data automatically)
$beers = $punkApi->getBeers();

// Check if the fallback was used
if ($punkApi->usedFallback()) {
    echo "Results came from bundled local data";
}

API Versions

The wrapper defaults to v3 (recommended). The legacy v2 API is still supported but may be offline.

// v3 (default) — https://punkapi-alxiw.amvera.io/v3/
$punkApi = PunkApi::create();

// v2 (legacy) — https://api.punkapi.com/v2/
$punkApi = PunkApi::create('v2');

Offline Fallback

All 415 beers from DIY Dog v8 are bundled in data/beers.json. When the live API can't be reached (connection timeout, DNS failure, etc.), the wrapper automatically filters and paginates from this local dataset. The same query parameters work identically whether hitting the API or the fallback.

Use usedFallback() to check which source was used:

$beers = $punkApi->named('punk')->getBeers();

if ($punkApi->usedFallback()) {
    // data came from local bundle
}

Methods

Creating an Instance

$punkApi = new PunkApi();          // v3 by default
$punkApi = PunkApi::create();      // static constructor
$punkApi = PunkApi::create('v2');   // use legacy v2 API

Querying Beers

getBeers()        // Returns an array of beer objects matching current params
getBeerById($id)  // Returns an array with a single beer by ID
getRandomBeer()   // Returns an array with a single random beer

Building the Endpoint

getEndpoint()     // Returns the URL that would be hit (does not make a request)

Parameters

Use addParams() with an associative array, or the chainable helper methods:

Parameter	Type	Description
`abv_gt`	number	Beers with ABV greater than this
`abv_lt`	number	Beers with ABV less than this
`ibu_gt`	number	Beers with IBU greater than this
`ibu_lt`	number	Beers with IBU less than this
`ebc_gt`	number	Beers with EBC greater than this
`ebc_lt`	number	Beers with EBC less than this
`beer_name`	string	Partial name match (e.g. "punk" matches Punk IPA)
`yeast`	string	Partial yeast name match
`hops`	string	Partial hops name match
`malt`	string	Partial malt name match
`food`	string	Partial food pairing match
`brewed_before`	string	Beers brewed before this date (mm-yyyy)
`brewed_after`	string	Beers brewed after this date (mm-yyyy)
`page`	number	Page number for pagination
`per_page`	number	Results per page (default: 25 for v2, 30 for v3)
`ids`	string	Comma-separated IDs for v3, pipe-separated for v2

Chainable Helper Methods

$punkApi->abvAbove(4)
    ->abvBelow(9)
    ->named('punk')
    ->getBeers();

All helpers: abvAbove(), abvBelow(), ibuAbove(), ibuBelow(), ebcAbove(), ebcBelow(), named(), yeast(), brewedBefore(), brewedAfter(), hops(), malt(), food(), page(), perPage(), ids()

The ids() method accepts an array of IDs or a string. It automatically formats them for the active API version (commas for v3, pipes for v2).

Managing Parameters

addParams(['abv_gt' => 4, 'beer_name' => 'punk'])  // Add params (chainable)
removeParams('beer_name', 'abv_gt')                  // Remove specific params (chainable)
clearParams()                                         // Remove all params (chainable)

Examples

use billythekid\PunkApi;

$punkApi = PunkApi::create();

// Get all beers with ABV between 4 and 9, named "punk"
$beers = $punkApi
    ->abvAbove(4)
    ->abvBelow(9)
    ->named('punk')
    ->getBeers();

// Same thing with addParams
$beers = $punkApi
    ->addParams(['abv_gt' => 4, 'abv_lt' => 9, 'beer_name' => 'punk'])
    ->getBeers();

// Get a specific beer
$beer = $punkApi->getBeerById(1);

// Get a random beer
$beer = $punkApi->getRandomBeer();

// Check the endpoint without making a request
$url = $punkApi->named('ipa')->getEndpoint();
// https://punkapi-alxiw.amvera.io/v3/beers?beer_name=ipa&page=1

// Get beers by multiple IDs
$beers = $punkApi->ids([1, 5, 10])->getBeers();

Changelog

v 2.0.1

Bugfix - ids() now normalizes separators automatically (pipes → commas on v3, commas → pipes on v2) so existing code passing pipe-separated strings continues to work

v 2.0.0

Breaking: Removed API key parameter from constructor (v3 API requires no auth)
Breaking: Requires PHP >= 8.3
Default API changed to v3 (punkapi-alxiw.amvera.io)
Added offline fallback with bundled data (415 beers from DIY Dog v8)
Added usedFallback() method
ids() now uses commas for v3 (pipes still used for v2)
Updated to Guzzle ^7.0 and PHPUnit ^13.0

v 1.1.2 - Mar 23, 2017

Bugfix - not passing a param to create() threw an error

v 1.1.1 - Feb 10, 2017

Bugfix - perPage() wasn't working properly
Added more tests

v 1.1.0 - Feb 10, 2017

Non-breaking update to use version 2 of the Punk API by default
Added ids() method and ids parameter
Added tests

v 1.0.0 - Oct 15, 2016

Initial release

License

MIT

billythekid / punk-api

Maintainers

Package info

Statistics

Security