README

Introduction

This package is a PHP wrapper for the IGDB version 4 API for retrieving game information. It contains the following:

All the IGDB v4 endpoints
Authentication package for retrieving the access token
Advanced query builder
Webhook management and incoming notification handling

System Requirements

Requires PHP 8.4 or later; Using the latest PHP version whenever possible is recommended.

Installation

Run the following to install this package:

$ composer require kris-kuiper/igdbv4

Authentication

To use the IGDB API you must have a Client ID and Access Token. Full information regarding acquiring these can be found at https://dev.twitch.tv/docs/authentication.

However, to get started immediately:

Sign Up with Twitch for a free account
Register your application
Manage your newly created application
Generate a Client Secret by pressing [New Secret]
Take note of the Client ID and Client Secret

When you got the Client ID and Client Secret, you can use the Authentication class to get an access token.

Example retrieving the access token

use KrisKuiper\IGDBV4\Authentication\AuthConfig;
use KrisKuiper\IGDBV4\Authentication\Authentication;
use GuzzleHttp\Client;

$config = new AuthConfig('your client id', 'your secret');
$client = new Client();
$authentication = new Authentication($client, $config);
$token = $authentication->obtainToken();

//The token will hold all the information you need to create a request to the IGDB API
$token->getAccessToken(); 
$token->getExpiration(); //The amount of seconds this token is valid

Note: An access token is approximately valid for 60 days. It is recommended to save the access token and expiration time for later use, so there is no need to generate a new access token for every request.

Endpoints

Every endpoint listed can be request by calling the endpoints name and has the following methods:

findById() - Find an item by its identifier (i.e. find a game by id)
list() - Returns a list of items (i.e. list all screenshots of a specific game)
query() - Execute a raw query on the current endpoint (i.e. execute a custom query to find a specific genre)

Only the game, platform, collection, character and theme endpoints supports also the search() method.

Below is a list of the supported endpoints.


Age rating content description	Game	Platform family
Age rating	Game engine	Platform logo
Alternative name	Game engine logo	Platform version company
Artwork	Game mode	Platform version
Character	Game version	Platform version release date
Character mug shot	Game version feature	Platform website
Collection	Game version feature value	Player perspective
Company	Game video	Screenshot
Company logo	Genre	Search
Company website	Involved company	Theme
Cover	Keyword	Website
External game	Multiplayer mode
Franchise	Platform

Example fetching game(s), platform(s) and genre(s):

use GuzzleHttp\Client;
use KrisKuiper\IGDBV4\IGDB;
use KrisKuiper\IGDBV4\Authentication\ValueObjects\AccessConfig;

$client = new Client();
$config = new AccessConfig('your client id', 'your access token');
$igdb = new IGDB($client, $config);

//Games
$igdb->game()->findById(375); //Find a game by id with optional selecting fields
$igdb->game()->findById(375, ['name', 'storyline', 'platforms.*']); //Find a game by id and specifying the fields to return
$igdb->game()->search('Metal Gear Solid'); //Search games by title
$igdb->game()->search('Metal Gear Solid', ['name', 'storyline', 'platforms.*']); //Search games by title and specifying the fields to return
$igdb->game()->list(); //List all games (limit will be 500 as default)
$igdb->game()->list(50, 20); //Setting an offset and limit (for pagination purposes)
$igdb->game()->query('fields name, storyline, platforms.*; where platforms = (7,9); sort id asc; limit 50'); //Using a custom query (see the Advanced Query builder section for creating queries programmatically)

//Platforms
$igdb->platform()->findById(5, ['name', 'slug']);
$igdb->platform()->list();
$igdb->platform()->search('Playstation');
$igdb->platform()->query('fields name, slug; limit 500; sort id;');

//Genres
$igdb->genre()->findById(5, ['name', 'slug']);
$igdb->genre()->list();
$igdb->genre()->query('fields name, slug; limit 500; sort id;');

Note: All the listed endpoints are available through the IGDB class.

Advanced Query Builder

The query builder lets you programmatically create queries which you can use for each endpoint calling the query() method.

It contains the following methods:

fields() (selecting specific fields)
exclude() (excluding specific fields)
search()
where() (where, whereIn and grouping where's)
orWhere() (only after a where)
sort()
offset()
limit()

Example using the query builder with the "games" endpoint

use GuzzleHttp\Client;
use KrisKuiper\IGDBV4\IGDB;
use KrisKuiper\IGDBV4\Authentication\ValueObjects\AccessConfig;
use KrisKuiper\IGDBV4\QueryBuilder\Query;

$client = new Client();
$config = new AccessConfig('your client id', 'your access token');
$igdb = new IGDB($client, $config);

//fields name, storyline, platforms.*; where platforms = (7, 9) & genre != 45; sort id asc; limit 20;
$query = (new Query())
    ->fields('name', 'storyline', 'platforms.*')
    ->where('platforms', [7, 9])
    ->where('genre', 45, '!=')
    ->sort('id')
    ->limit(20)
    ->build();
    
$igdb->game()->query($query);

Examples using the query builder

use KrisKuiper\IGDBV4\QueryBuilder\Query;

//fields name, storyline; platforms.*; where id = 375;
$query = (new Query())
    ->fields('name', 'storyline', 'platforms.*')
    ->where('id', 375)
    ->build();
    
//fields name, storyline; search "Metal Gear Solid; limit 50;
$query = (new Query())
    ->fields('name', 'storyline', 'platforms.*')
    ->search('Metal Gear Solid')
    ->limit(50)
    ->build();

//fields *; exclude genre, platforms, keywords; sort name desc; limit 50;
$query = (new Query())
    ->fields('*')
    ->exclude('genre', 'platform', 'keywords')
    ->limit(50)
    ->sort('name', 'desc')
    ->build();

Query builder advanced where conditions

use KrisKuiper\IGDBV4\QueryBuilder\Query;

//fields name; where genre = 25 & platforms = 5;
$query = (new Query())
    ->fields('name')
    ->where('genre', 25)
    ->where('platforms', 5)
    ->build();

//fields name; where platforms >= 5 & platforms <= 10;
$query = (new Query())
    ->fields('name')
    ->where('platforms', 5, '>=')
    ->where('platforms', 10, '<=')
    ->build();
    
//fields name; where genre = 25 | platforms = (5, 7, 9);
$query = (new Query())
    ->fields('name')
    ->where('genre', 25)
    ->orWhere('platforms', [5, 7, 9])
    ->build();

//fields name; where genre = 25 | (platforms = 5 | platforms = 9 | platforms = 12) & id = 375;
$query = (new Query())
    ->fields('name')
    ->where('genre', 25)
    ->orWhere(function($query) {
        $query
            ->where('platforms', 5)
            ->orWhere('platforms', 9)
            ->orWhere('platforms', 12);
    })
    ->where('id', 375)
    ->build();

Webhooks

Instead of polling the API for changes, IGDB can push data to you whenever an entity is added, updated or deleted. This package supports both managing your webhooks and handling the incoming notifications.

Full information can be found in the IGDB webhook documentation.

Managing webhooks

Webhooks are registered per endpoint and per method (create, update or delete). The secret is a value of your choice that IGDB will send back in the X-Secret header of every notification, so you can verify the request really came from IGDB.

use GuzzleHttp\Client;
use KrisKuiper\IGDBV4\IGDB;
use KrisKuiper\IGDBV4\Authentication\ValueObjects\AccessConfig;
use KrisKuiper\IGDBV4\Enums\WebhookMethod;

$client = new Client();
$config = new AccessConfig('your client id', 'your access token');
$igdb = new IGDB($client, $config);

//Register a webhook that fires when a new game is created
$webhook = $igdb->webhooks()->register('games', 'https://example.com/igdb/webhook', WebhookMethod::CREATE, 'your-secret');
$webhook->getId();      //The unique webhook id
$webhook->isActive();   //Whether the webhook is currently active

//Retrieve all registered webhooks (returns a typed WebhookCollection)
foreach ($igdb->webhooks()->all() as $webhook) {
    $webhook->getUrl();
}

//Retrieve a single webhook by its id (returns null when it does not exist)
$igdb->webhooks()->find($webhook->getId());

//Send a test notification: delivers the game with id 1337 to your registered "games" create webhook
$igdb->webhooks()->test('games', $webhook->getId(), 1337);

//Remove a webhook (returns the deleted webhook id)
$igdb->webhooks()->delete($webhook->getId());

Tip: A webhook is set to inactive after 5 failed deliveries. Re-register it on service start to make sure it is always active.

Handling incoming notifications

When IGDB delivers a notification, validate and parse it with the WebhookReceiver. It is framework-agnostic and accepts any PSR-7 ServerRequestInterface. It verifies the X-Secret and User-Agent headers for you and throws a WebhookException when the request can not be trusted.

use KrisKuiper\IGDBV4\Webhooks\WebhookReceiver;
use KrisKuiper\IGDBV4\Exceptions\WebhookException;
use KrisKuiper\IGDBV4\Enums\WebhookMethod;

//$request is a PSR-7 ServerRequestInterface provided by your framework
$receiver = new WebhookReceiver('your-secret');

try {
    $payload = $receiver->receive($request);
} catch (WebhookException $exception) {
    //Invalid secret, wrong user agent or an unparsable body: reject the request
    http_response_code(403);
    return;
}

$payload->getEndpoint();    //e.g. "games"
$payload->getOperation();   //WebhookMethod::CREATE, ::UPDATE or ::DELETE
$payload->getId();          //The id of the affected entity
$payload->getData();        //The unexpanded entity (only the id is present for delete notifications)

//Always answer within 15 seconds with a 200 OK so IGDB keeps the webhook active
http_response_code(200);

Note: incoming X-Endpoint values are normalized to their lowercase slug (IGDB delivers Games while webhooks are registered as games), and the X-Operation value is matched case-insensitively.

Handling test deliveries

Deliveries triggered through the test API ($igdb->webhooks()->test(...)) differ from real deliveries: IGDB sends them with a generic Java/<version> user agent and without the X-Endpoint and X-Operation headers (the X-Secret header is present). They would therefore always be rejected by receive(). Use receiveTest() instead, which only verifies the secret and returns the raw entity:

$receiver = new WebhookReceiver('your-secret');
$data = $receiver->receiveTest($request); //Verifies X-Secret, returns the entity object
$data->id;

Run Unit Test

Install phpunit in your environment and run:

$ php ./vendor/bin/phpunit

Questions and Feedback

Questions that are not addressed in the manual should be directed to the relevant repository, as linked above.

If you find code in this release behaving in an unexpected manner or contrary to its documented behavior, please create an issue with the relevant repository, as linked above.

License

You can find a copy of this license in LICENSE.md.

kris-kuiper / igdbv4

Maintainers

Package info

Statistics

Security