{"id":42236338,"url":"https://github.com/kris-kuiper/igdb-v4-api","last_synced_at":"2026-06-04T09:00:28.082Z","repository":{"id":57009207,"uuid":"409708060","full_name":"kris-kuiper/IGDB-v4-API","owner":"kris-kuiper","description":"Wrapper for IGDB API v4","archived":false,"fork":false,"pushed_at":"2026-06-03T23:18:53.000Z","size":102,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-04T02:10:29.753Z","etag":null,"topics":["api","client","game","igdb","php","query","request","wrapper"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kris-kuiper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-09-23T18:47:10.000Z","updated_at":"2026-06-03T23:18:55.000Z","dependencies_parsed_at":"2024-07-16T00:48:46.834Z","dependency_job_id":"84e15a52-7ea3-4769-a8ba-c3fe03e654e3","html_url":"https://github.com/kris-kuiper/IGDB-v4-API","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/kris-kuiper/IGDB-v4-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kris-kuiper%2FIGDB-v4-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kris-kuiper%2FIGDB-v4-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kris-kuiper%2FIGDB-v4-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kris-kuiper%2FIGDB-v4-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kris-kuiper","download_url":"https://codeload.github.com/kris-kuiper/IGDB-v4-API/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kris-kuiper%2FIGDB-v4-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33897568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","game","igdb","php","query","request","wrapper"],"created_at":"2026-01-27T03:39:30.178Z","updated_at":"2026-06-04T09:00:28.052Z","avatar_url":"https://github.com/kris-kuiper.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"IGDB V4 PHP API\r\n====================\r\n\r\n[![License](https://poser.pugx.org/kris-kuiper/igdbv4/license)](https://packagist.org/packages/kris-kuiper/igdbv4)\r\n[![Total Downloads](https://poser.pugx.org/kris-kuiper/igdbv4/downloads)](https://packagist.org/packages/kris-kuiper/igdbv4)\r\n\r\n## Introduction\r\nThis package is a PHP wrapper for the IGDB version 4 API for retrieving game information. It contains the following:\r\n- All the IGDB v4 [endpoints](https://api-docs.igdb.com/?shell#endpoints)\r\n- Authentication package for retrieving the access token\r\n- Advanced query builder\r\n- [Webhook](https://api-docs.igdb.com/?shell#webhooks) management and incoming notification handling\r\n\r\n***\r\n\r\n### System Requirements\r\nRequires PHP 8.4 or later; Using the latest PHP version whenever possible is recommended.\r\n\r\n***\r\n\r\n### Installation\r\nRun the following to install this package:\r\n```bash\r\n$ composer require kris-kuiper/igdbv4\r\n```\r\n\r\n***\r\n\r\n### Authentication\r\nTo use the IGDB API you must have a Client ID and Access Token.\r\nFull information regarding acquiring these can be found at https://dev.twitch.tv/docs/authentication.\r\n\r\nHowever, to get started immediately:\r\n\r\n- Sign Up with [Twitch](https://www.twitch.tv) for a free account\r\n- [Register](https://dev.twitch.tv/console/apps/create) your application\r\n- [Manage](https://dev.twitch.tv/console/apps) your newly created application\r\n- Generate a Client Secret by pressing [New Secret]\r\n- Take note of the Client ID and Client Secret\r\n\r\nWhen you got the Client ID and Client Secret, you can use the `Authentication` class to get an access token.\r\n\r\n#### Example retrieving the access token\r\n```php\r\nuse KrisKuiper\\IGDBV4\\Authentication\\AuthConfig;\r\nuse KrisKuiper\\IGDBV4\\Authentication\\Authentication;\r\nuse GuzzleHttp\\Client;\r\n\r\n$config = new AuthConfig('your client id', 'your secret');\r\n$client = new Client();\r\n$authentication = new Authentication($client, $config);\r\n$token = $authentication-\u003eobtainToken();\r\n\r\n//The token will hold all the information you need to create a request to the IGDB API\r\n$token-\u003egetAccessToken(); \r\n$token-\u003egetExpiration(); //The amount of seconds this token is valid\r\n```\r\n\r\n*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.*\r\n\r\n***\r\n\r\n### Endpoints\r\nEvery endpoint listed can be request by calling the endpoints name and has the following methods:\r\n- `findById()` - Find an item by its identifier (i.e. find a game by id)\r\n- `list()` - Returns a list of items (i.e. list all screenshots of a specific game)\r\n- `query()` - Execute a raw query on the current endpoint (i.e. execute a custom query to find a specific genre)\r\n\r\nOnly the game, platform, collection, character and theme endpoints supports also the `search()` method.\r\n\r\nBelow is a list of the supported endpoints.\r\n\r\n|                                                                                                   |                                                                                           |                                                                                                 |\r\n|---------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|\r\n| [Age rating content description](https://api-docs.igdb.com/?shell#age-rating-content-description) | [Game](https://api-docs.igdb.com/?shell#game)                                             | [Platform family](https://api-docs.igdb.com/?shell#platform-family)                             |\r\n| [Age rating](https://api-docs.igdb.com/?shell#age-rating)                                         | [Game engine](https://api-docs.igdb.com/?shell#game-engine)                               | [Platform logo](https://api-docs.igdb.com/?shell#platform-logo)                                 |\r\n| [Alternative name](https://api-docs.igdb.com/?shell#alternative-name)                             | [Game engine logo](https://api-docs.igdb.com/?shell#game-engine-logo)                     | [Platform version company](https://api-docs.igdb.com/?shell#platform-version-company)           |\r\n| [Artwork](https://api-docs.igdb.com/?shell#artwork)                                               | [Game mode](https://api-docs.igdb.com/?shell#game-mode)                                   | [Platform version](https://api-docs.igdb.com/?shell#platform-version)                           |\r\n| [Character](https://api-docs.igdb.com/?shell#character)                                           | [Game version](https://api-docs.igdb.com/?shell#game-version)                             | [Platform version release date](https://api-docs.igdb.com/?shell#platform-version-release-date) |\r\n| [Character mug shot](https://api-docs.igdb.com/?shell#character-mug-shot)                         | [Game version feature](https://api-docs.igdb.com/?shell#game-version-feature)             | [Platform website](https://api-docs.igdb.com/?shell#platform-website)                           |\r\n| [Collection](https://api-docs.igdb.com/?shell#collection)                                         | [Game version feature value](https://api-docs.igdb.com/?shell#game-version-feature-value) | [Player perspective](https://api-docs.igdb.com/?shell#player-perspective)                       |\r\n| [Company](https://api-docs.igdb.com/?shell#company)                                               | [Game video](https://api-docs.igdb.com/?shell#game-video)                                 | [Screenshot](https://api-docs.igdb.com/?shell#screenshot)                                       |\r\n| [Company logo](https://api-docs.igdb.com/?shell#company-logo)                                     | [Genre](https://api-docs.igdb.com/?shell#genre)                                           | [Search](https://api-docs.igdb.com/?shell#search)                                               |\r\n| [Company website](https://api-docs.igdb.com/?shell#company-website)                               | [Involved company](https://api-docs.igdb.com/?shell#involved-company)                     | [Theme](https://api-docs.igdb.com/?shell#theme)                                                 |\r\n| [Cover](https://api-docs.igdb.com/?shell#cover)                                                   | [Keyword](https://api-docs.igdb.com/?shell#keyword)                                       | [Website](https://api-docs.igdb.com/?shell#website)                                             |\r\n| [External game](https://api-docs.igdb.com/?shell#external-game)                                   | [Multiplayer mode](https://api-docs.igdb.com/?shell#multiplayer-mode)                     | \r\n| [Franchise](https://api-docs.igdb.com/?shell#franchise)                                           | [Platform](https://api-docs.igdb.com/?shell#platform)                                     |   \r\n\r\n#### Example fetching game(s), platform(s) and genre(s):\r\n```php\r\nuse GuzzleHttp\\Client;\r\nuse KrisKuiper\\IGDBV4\\IGDB;\r\nuse KrisKuiper\\IGDBV4\\Authentication\\ValueObjects\\AccessConfig;\r\n\r\n$client = new Client();\r\n$config = new AccessConfig('your client id', 'your access token');\r\n$igdb = new IGDB($client, $config);\r\n\r\n//Games\r\n$igdb-\u003egame()-\u003efindById(375); //Find a game by id with optional selecting fields\r\n$igdb-\u003egame()-\u003efindById(375, ['name', 'storyline', 'platforms.*']); //Find a game by id and specifying the fields to return\r\n$igdb-\u003egame()-\u003esearch('Metal Gear Solid'); //Search games by title\r\n$igdb-\u003egame()-\u003esearch('Metal Gear Solid', ['name', 'storyline', 'platforms.*']); //Search games by title and specifying the fields to return\r\n$igdb-\u003egame()-\u003elist(); //List all games (limit will be 500 as default)\r\n$igdb-\u003egame()-\u003elist(50, 20); //Setting an offset and limit (for pagination purposes)\r\n$igdb-\u003egame()-\u003equery('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)\r\n\r\n//Platforms\r\n$igdb-\u003eplatform()-\u003efindById(5, ['name', 'slug']);\r\n$igdb-\u003eplatform()-\u003elist();\r\n$igdb-\u003eplatform()-\u003esearch('Playstation');\r\n$igdb-\u003eplatform()-\u003equery('fields name, slug; limit 500; sort id;');\r\n\r\n//Genres\r\n$igdb-\u003egenre()-\u003efindById(5, ['name', 'slug']);\r\n$igdb-\u003egenre()-\u003elist();\r\n$igdb-\u003egenre()-\u003equery('fields name, slug; limit 500; sort id;');\r\n```\r\n\r\n*Note: All the listed endpoints are available through the `IGDB` class.*\r\n\r\n***\r\n\r\n### Advanced Query Builder\r\nThe query builder lets you programmatically create queries which you can use for each endpoint calling the `query()` method.\r\n\r\nIt contains the following methods:\r\n- `fields()` (selecting specific fields)\r\n- `exclude()` (excluding specific fields)\r\n- `search()` \r\n- `where()` (where, whereIn and grouping where's)\r\n- `orWhere()` (only after a where)\r\n- `sort()`\r\n- `offset()`\r\n- `limit()`\r\n\r\n#### Example using the query builder with the \"games\" endpoint\r\n```php\r\nuse GuzzleHttp\\Client;\r\nuse KrisKuiper\\IGDBV4\\IGDB;\r\nuse KrisKuiper\\IGDBV4\\Authentication\\ValueObjects\\AccessConfig;\r\nuse KrisKuiper\\IGDBV4\\QueryBuilder\\Query;\r\n\r\n$client = new Client();\r\n$config = new AccessConfig('your client id', 'your access token');\r\n$igdb = new IGDB($client, $config);\r\n\r\n//fields name, storyline, platforms.*; where platforms = (7, 9) \u0026 genre != 45; sort id asc; limit 20;\r\n$query = (new Query())\r\n    -\u003efields('name', 'storyline', 'platforms.*')\r\n    -\u003ewhere('platforms', [7, 9])\r\n    -\u003ewhere('genre', 45, '!=')\r\n    -\u003esort('id')\r\n    -\u003elimit(20)\r\n    -\u003ebuild();\r\n    \r\n$igdb-\u003egame()-\u003equery($query);\r\n```\r\n\r\n#### Examples using the query builder\r\n```php\r\nuse KrisKuiper\\IGDBV4\\QueryBuilder\\Query;\r\n\r\n//fields name, storyline; platforms.*; where id = 375;\r\n$query = (new Query())\r\n    -\u003efields('name', 'storyline', 'platforms.*')\r\n    -\u003ewhere('id', 375)\r\n    -\u003ebuild();\r\n    \r\n//fields name, storyline; search \"Metal Gear Solid; limit 50;\r\n$query = (new Query())\r\n    -\u003efields('name', 'storyline', 'platforms.*')\r\n    -\u003esearch('Metal Gear Solid')\r\n    -\u003elimit(50)\r\n    -\u003ebuild();\r\n\r\n//fields *; exclude genre, platforms, keywords; sort name desc; limit 50;\r\n$query = (new Query())\r\n    -\u003efields('*')\r\n    -\u003eexclude('genre', 'platform', 'keywords')\r\n    -\u003elimit(50)\r\n    -\u003esort('name', 'desc')\r\n    -\u003ebuild();\r\n```\r\n\r\n#### Query builder advanced where conditions\r\n```php\r\nuse KrisKuiper\\IGDBV4\\QueryBuilder\\Query;\r\n\r\n//fields name; where genre = 25 \u0026 platforms = 5;\r\n$query = (new Query())\r\n    -\u003efields('name')\r\n    -\u003ewhere('genre', 25)\r\n    -\u003ewhere('platforms', 5)\r\n    -\u003ebuild();\r\n\r\n//fields name; where platforms \u003e= 5 \u0026 platforms \u003c= 10;\r\n$query = (new Query())\r\n    -\u003efields('name')\r\n    -\u003ewhere('platforms', 5, '\u003e=')\r\n    -\u003ewhere('platforms', 10, '\u003c=')\r\n    -\u003ebuild();\r\n    \r\n//fields name; where genre = 25 | platforms = (5, 7, 9);\r\n$query = (new Query())\r\n    -\u003efields('name')\r\n    -\u003ewhere('genre', 25)\r\n    -\u003eorWhere('platforms', [5, 7, 9])\r\n    -\u003ebuild();\r\n\r\n//fields name; where genre = 25 | (platforms = 5 | platforms = 9 | platforms = 12) \u0026 id = 375;\r\n$query = (new Query())\r\n    -\u003efields('name')\r\n    -\u003ewhere('genre', 25)\r\n    -\u003eorWhere(function($query) {\r\n        $query\r\n            -\u003ewhere('platforms', 5)\r\n            -\u003eorWhere('platforms', 9)\r\n            -\u003eorWhere('platforms', 12);\r\n    })\r\n    -\u003ewhere('id', 375)\r\n    -\u003ebuild();\r\n```\r\n\r\n***\r\n\r\n### Webhooks\r\nInstead 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.\r\n\r\nFull information can be found in the IGDB [webhook documentation](https://api-docs.igdb.com/?shell#webhooks).\r\n\r\n#### Managing webhooks\r\nWebhooks 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.\r\n\r\n```php\r\nuse GuzzleHttp\\Client;\r\nuse KrisKuiper\\IGDBV4\\IGDB;\r\nuse KrisKuiper\\IGDBV4\\Authentication\\ValueObjects\\AccessConfig;\r\nuse KrisKuiper\\IGDBV4\\Enums\\WebhookMethod;\r\n\r\n$client = new Client();\r\n$config = new AccessConfig('your client id', 'your access token');\r\n$igdb = new IGDB($client, $config);\r\n\r\n//Register a webhook that fires when a new game is created\r\n$webhook = $igdb-\u003ewebhooks()-\u003eregister('games', 'https://example.com/igdb/webhook', WebhookMethod::CREATE, 'your-secret');\r\n$webhook-\u003egetId();      //The unique webhook id\r\n$webhook-\u003eisActive();   //Whether the webhook is currently active\r\n\r\n//Retrieve all registered webhooks (returns a typed WebhookCollection)\r\nforeach ($igdb-\u003ewebhooks()-\u003eall() as $webhook) {\r\n    $webhook-\u003egetUrl();\r\n}\r\n\r\n//Retrieve a single webhook by its id (returns null when it does not exist)\r\n$igdb-\u003ewebhooks()-\u003efind($webhook-\u003egetId());\r\n\r\n//Send a test notification: delivers the game with id 1337 to your registered \"games\" create webhook\r\n$igdb-\u003ewebhooks()-\u003etest('games', $webhook-\u003egetId(), 1337);\r\n\r\n//Remove a webhook (returns the deleted webhook id)\r\n$igdb-\u003ewebhooks()-\u003edelete($webhook-\u003egetId());\r\n```\r\n\r\n*Tip: A webhook is set to inactive after 5 failed deliveries. Re-register it on service start to make sure it is always active.*\r\n\r\n#### Handling incoming notifications\r\nWhen 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.\r\n\r\n```php\r\nuse KrisKuiper\\IGDBV4\\Webhooks\\WebhookReceiver;\r\nuse KrisKuiper\\IGDBV4\\Exceptions\\WebhookException;\r\nuse KrisKuiper\\IGDBV4\\Enums\\WebhookMethod;\r\n\r\n//$request is a PSR-7 ServerRequestInterface provided by your framework\r\n$receiver = new WebhookReceiver('your-secret');\r\n\r\ntry {\r\n    $payload = $receiver-\u003ereceive($request);\r\n} catch (WebhookException $exception) {\r\n    //Invalid secret, wrong user agent or an unparsable body: reject the request\r\n    http_response_code(403);\r\n    return;\r\n}\r\n\r\n$payload-\u003egetEndpoint();    //e.g. \"games\"\r\n$payload-\u003egetOperation();   //WebhookMethod::CREATE, ::UPDATE or ::DELETE\r\n$payload-\u003egetId();          //The id of the affected entity\r\n$payload-\u003egetData();        //The unexpanded entity (only the id is present for delete notifications)\r\n\r\n//Always answer within 15 seconds with a 200 OK so IGDB keeps the webhook active\r\nhttp_response_code(200);\r\n```\r\n\r\n*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.*\r\n\r\n#### Handling test deliveries\r\nDeliveries triggered through the test API (`$igdb-\u003ewebhooks()-\u003etest(...)`) differ from real deliveries: IGDB sends them with a generic `Java/\u003cversion\u003e` 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:\r\n\r\n```php\r\n$receiver = new WebhookReceiver('your-secret');\r\n$data = $receiver-\u003ereceiveTest($request); //Verifies X-Secret, returns the entity object\r\n$data-\u003eid;\r\n```\r\n\r\n***\r\n\r\n### Run Unit Test\r\nInstall phpunit in your environment and run:\r\n\r\n```bash\r\n$ php ./vendor/bin/phpunit\r\n```\r\n\r\n***\r\n\r\n### Questions and Feedback\r\nQuestions that are not addressed in the manual should be directed to the\r\nrelevant repository, as linked above.\r\n\r\nIf you find code in this release behaving in an unexpected manner or\r\ncontrary to its documented behavior, please create an issue with the relevant\r\nrepository, as linked above.\r\n\r\n***\r\n\r\n### License\r\nYou can find a copy of this license in [LICENSE.md](LICENSE.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkris-kuiper%2Figdb-v4-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkris-kuiper%2Figdb-v4-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkris-kuiper%2Figdb-v4-api/lists"}