Documentation

PunkApi
in package

Class PunkApi Wrapper class for querying the PunkAPI.

Supports the v3 API at https://punkapi-alxiw.amvera.io/v3/ (default) and the legacy v2 API at https://api.punkapi.com/v2/. Falls back to bundled local data (415 beers from DIY Dog v8) when the API is unreachable.

Table of Contents

Constants

IMAGE_BASE_URL  = 'https://punkapi-alxiw.amvera.io/v3/images/'
IMAGE_FALLBACK_BASE_URL  = 'https://raw.githubusercontent.com/alxiw/punkapi/master/img/'

Properties

$allowedParams  : array<string|int, mixed>
$apiRoot  : string
$apiVersion  : string
$client  : Client
$localData  : array<string|int, mixed>|null
$params  : array<string|int, mixed>
$usedFallback  : bool

Methods

__construct()  : mixed
PunkApi constructor.
abvAbove()  : $this
Sets the abv_gt parameter to the given number.
abvBelow()  : $this
Sets the abv_lt parameter to the given number.
addParams()  : $this
Adds parameter options to this object.
brewedAfter()  : $this
Sets the brewed_after parameter to the given date
brewedBefore()  : $this
Sets the brewed_before parameter to the given date
clearParams()  : $this
Empties the parameters of this object.
create()  : PunkApi
Static constructor.
ebcAbove()  : $this
Sets the ebc_gt parameter to the given number.
ebcBelow()  : $this
Sets the ebc_lt parameter to the given number.
food()  : $this
Sets the food parameter to the given food name
getBeerById()  : array<string|int, mixed>
Get a beer by its ID number.
getBeers()  : array<string|int, mixed>
Queries the PunkAPI with the current parameters.
getEndpoint()  : string
Returns the URL that would be hit at the current state of this object.
getRandomBeer()  : array<string|int, mixed>
Get a random beer.
hops()  : $this
Sets the hops parameter to the given hops name
ibuAbove()  : $this
Sets the ibu_gt parameter to the given number.
ibuBelow()  : $this
Sets the ibu_lt parameter to the given number.
ids()  : $this
Sets the ids parameter to the given ids.
malt()  : $this
Sets the malt parameter to the given malt name
named()  : $this
Sets the beer_name parameter to the given beer name.
page()  : $this
Set the parameters to return the given page of results
perPage()  : $this
Set the number of beers to return per page
removeParams()  : $this
Removes given parameters from this object.
usedFallback()  : bool
Returns true if the last request used the bundled fallback data instead of the live API.
yeast()  : $this
Sets the yeast parameter to the given yeast name
cleanParams()  : array<string|int, mixed>
Helper method, parameter validation.
filterLocalData()  : array<string|int, mixed>
Applies the current parameters to filter the local beer data, replicating the API's filtering and pagination behavior.
loadLocalData()  : array<string|int, mixed>
Loads the bundled beer data from the JSON file.
normalizeImageUrls()  : array<string|int, mixed>
Normalizes image fields on an array of beer objects.
parseBrewDate()  : int|null
Parses a brew date string into a comparable integer (YYYYMM format).

Constants

IMAGE_BASE_URL

private mixed IMAGE_BASE_URL = 'https://punkapi-alxiw.amvera.io/v3/images/'

IMAGE_FALLBACK_BASE_URL

private mixed IMAGE_FALLBACK_BASE_URL = 'https://raw.githubusercontent.com/alxiw/punkapi/master/img/'

Properties

$allowedParams

private array<string|int, mixed> $allowedParams = [ 'abv_gt', //number Returns all beers with ABV greater than the supplied number 'abv_lt', //number Returns all beers with ABV less than the supplied number 'ibu_gt', //number Returns all beers with IBU greater than the supplied number 'ibu_lt', //number Returns all beers with IBU less than the supplied number 'ebc_gt', //number Returns all beers with EBC greater than the supplied number 'ebc_lt', //number Returns all beers with EBC less than the supplied number 'beer_name', //string Returns all beers matching the supplied name (partial match) 'yeast', //string Returns all beers matching the supplied yeast name (partial match) 'brewed_before', //date Returns all beers brewed before this date (mm-yyyy or yyyy) 'brewed_after', //date Returns all beers brewed after this date (mm-yyyy or yyyy) 'hops', //string Returns all beers matching the supplied hops name (partial match) 'malt', //string Returns all beers matching the supplied malt name (partial match) 'food', //string Returns all beers matching the supplied food string (partial match) 'page', //number Return the beers from the page given (responses are paginated) 'per_page', //number Change the number of beers returned per page (default: 25 for v2, 30 for v3) 'ids', ]

$apiVersion

private string $apiVersion

$localData

private static array<string|int, mixed>|null $localData = null

$params

private array<string|int, mixed> $params = []

$usedFallback

private bool $usedFallback = false

Methods

__construct()

PunkApi constructor.

public __construct([string $apiVersion = 'v3' ][, Client|null $client = null ]) : mixed
Parameters
$apiVersion : string = 'v3'

API version to use: 'v3' (default, recommended) or 'v2' (legacy)

$client : Client|null = null

Optional Guzzle client for dependency injection / testing

abvAbove()

Sets the abv_gt parameter to the given number.

public abvAbove(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

abvBelow()

Sets the abv_lt parameter to the given number.

public abvBelow(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

addParams()

Adds parameter options to this object.

public addParams(array<string|int, mixed> $params) : $this
Parameters
$params : array<string|int, mixed>
Return values
$this

brewedAfter()

Sets the brewed_after parameter to the given date

public brewedAfter(string $date) : $this
Parameters
$date : string

format: mm-yyyy or yyyy

Return values
$this

brewedBefore()

Sets the brewed_before parameter to the given date

public brewedBefore(string $date) : $this
Parameters
$date : string

format: mm-yyyy or yyyy

Return values
$this

clearParams()

Empties the parameters of this object.

public clearParams() : $this
Return values
$this

create()

Static constructor.

public static create([string $apiVersion = 'v3' ][, Client|null $client = null ]) : PunkApi
Parameters
$apiVersion : string = 'v3'
$client : Client|null = null
Return values
PunkApi

ebcAbove()

Sets the ebc_gt parameter to the given number.

public ebcAbove(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

ebcBelow()

Sets the ebc_lt parameter to the given number.

public ebcBelow(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

food()

Sets the food parameter to the given food name

public food(string $foodName) : $this
Parameters
$foodName : string
Return values
$this

getBeerById()

Get a beer by its ID number.

public getBeerById(int $beerId) : array<string|int, mixed>

Falls back to bundled data if the API is unreachable.

Parameters
$beerId : int
Return values
array<string|int, mixed> —

containing a single beer \StdClass object

getBeers()

Queries the PunkAPI with the current parameters.

public getBeers() : array<string|int, mixed>

Falls back to bundled local data if the API is unreachable.

Return values
array<string|int, mixed> —

of beer \StdClass objects

getEndpoint()

Returns the URL that would be hit at the current state of this object.

public getEndpoint() : string
Return values
string

getRandomBeer()

Get a random beer.

public getRandomBeer() : array<string|int, mixed>

Falls back to a random beer from bundled data if the API is unreachable.

Return values
array<string|int, mixed> —

containing a single beer \StdClass object

hops()

Sets the hops parameter to the given hops name

public hops(string $hopsName) : $this
Parameters
$hopsName : string
Return values
$this

ibuAbove()

Sets the ibu_gt parameter to the given number.

public ibuAbove(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

ibuBelow()

Sets the ibu_lt parameter to the given number.

public ibuBelow(float|int $number) : $this
Parameters
$number : float|int
Return values
$this

ids()

Sets the ids parameter to the given ids.

public ids(array<string|int, mixed>|string $ids) : $this

Accepts an array of ID numbers or a pre-formatted string.

Parameters
$ids : array<string|int, mixed>|string
Return values
$this

malt()

Sets the malt parameter to the given malt name

public malt(string $maltName) : $this
Parameters
$maltName : string
Return values
$this

named()

Sets the beer_name parameter to the given beer name.

public named(string $beerName) : $this
Parameters
$beerName : string
Return values
$this

page()

Set the parameters to return the given page of results

public page(int $pageNumber) : $this
Parameters
$pageNumber : int
Return values
$this

perPage()

Set the number of beers to return per page

public perPage(int $number) : $this
Parameters
$number : int
Return values
$this

removeParams()

Removes given parameters from this object.

public removeParams(string ...$badParams) : $this
Parameters
$badParams : string
Return values
$this

usedFallback()

Returns true if the last request used the bundled fallback data instead of the live API.

public usedFallback() : bool
Return values
bool

yeast()

Sets the yeast parameter to the given yeast name

public yeast(string $yeastName) : $this
Parameters
$yeastName : string
Return values
$this

cleanParams()

Helper method, parameter validation.

private cleanParams(array<string|int, mixed> $params) : array<string|int, mixed>
Parameters
$params : array<string|int, mixed>
Return values
array<string|int, mixed>

filterLocalData()

Applies the current parameters to filter the local beer data, replicating the API's filtering and pagination behavior.

private filterLocalData(array<string|int, mixed> $beers) : array<string|int, mixed>
Parameters
$beers : array<string|int, mixed>
Return values
array<string|int, mixed>

loadLocalData()

Loads the bundled beer data from the JSON file.

private loadLocalData() : array<string|int, mixed>

Caches the result in a static property to avoid re-reading on every call.

Return values
array<string|int, mixed> —

of beer \StdClass objects

normalizeImageUrls()

Normalizes image fields on an array of beer objects.

private normalizeImageUrls(array<string|int, mixed> $beers) : array<string|int, mixed>

Sets image_url to the full v3 API image URL and image_url_fallback to the GitHub raw URL. Handles bare filenames (v3/fallback data), full v2 URLs (https://images.punkapi.com/v2/...), and already-normalized URLs.

Parameters
$beers : array<string|int, mixed>
Return values
array<string|int, mixed>

parseBrewDate()

Parses a brew date string into a comparable integer (YYYYMM format).

private parseBrewDate(string $date) : int|null

Supports formats: "MM/YYYY", "MM-YYYY", "YYYY"

Parameters
$date : string
Return values
int|null 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results