- Introduction
- Initializing Class
- Class Properties
- Options Parameters
- Public Methods
- Private Methods
- Endpoints
- Achievement
- Achievement Icon
- Age Rating
- Age Rating Content Description
- Alternative Name
- Artwork
- Character
- Character Mug Shot
- Collection
- Company
- Company Logo
- Company Website
- Cover
- External Game
- Feed
- Feed Follow
- Follow
- Franchise
- Game
- Game Engine
- Game Engine Logo
- Game Mode
- Game Version
- Game Version Feature
- Game Version Feature Value
- Game Video
- Genre
- Involved Company
- Keyword
- List
- List Entry
- Multiplayer Mode
- Page
- Page Background
- Page Logo
- Page Website
- Platform
- Platform Logo
- Platform Version
- Platform Version Company
- Platform Version Release Date
- Platform Website
- Player Perspective
- Product Family
- Pulse
- Pulse Group
- Pulse Source
- Pulse Url
- Rate
- Release Date
- Review
- Review Video
- Screenshot
- Search
- Theme
- Time To Beat
- Title
- Website
- Example Query
- Return Values
- Change Log
The class's main purpose is to provide a simple solution to fetch data from IGDB's database using PHP.
To use IGDB's database you have to register an account at https://api.igdb.com. For details on how to use the IGDB API, what endpoints can be used or for informations in general check out the Official Documentation of the IGDB API.
public IGDB::__construct ( string $key ) : void
After the class is imported in your project you can instantiate the class by passing your IGDB API Key to the constructor. The credentials will be verfied only by IGDB server when you send the query.
require 'class.igdb.php';
$IGDB = new IGDB('<YOUR API KEY>');From now on multiple request can be sent to the IGDB API with the same instance.
private IGDB::$API_URL ( string ): IGDB API URL. This is the address you have to send your query to.
private IGDB::$API_KEY ( string ): your personal API Key provided by IGDB. It's value is set by IGDB::__construct().
private IGDB::$CH ( resource ): CURL resource handler. Return value of curl_init(). You can close IGDB::close_handler() and reinitialize IGDB::reinit_handler() the session anytime.
For every endpoint method that fetching data from IGDB you will need to provide an $options array, that contains the parameters of the query.
Note: the order of the parameters in the
$optionsarray does not matter!
id ( array | number ) [ optional ]: one ore more item ID's.
// Providing one ID
$options = array(
'id' => 5
)
// Providing several ID's
$options = array(
'id' => array(5, 6, 7, 8)
);The new version of the IGDB API (v3) is handling item id's differently (from query perspective). Filtering the results by item id is now done by providing it in the
wherestatement of the query. During runtime the class will add this value there. You can provide the id's in thewherestatement as well.
search ( string ) [ optional ]: search based on name, results are sorted by similarity to the given search string.
// Provide search string
$options = array(
'search' => 'star wars'
);fields ( array | string ) [ optional ]: Fields are properties of an entity. For example, a Game field would be genres or release_dates. Some fields have properties of their own, for example, the genres field has the property name.
// Provide single or multiple fields as a string separated by comma
$options = array(
'fields' => 'id,name'
);
// Provide single or multiple fields as an array
$options = array(
'fields' => array('id', 'name');
);
// Get all fields in the result
$options = array(
'fields' => '*'
);limit ( number ) [ optional ]: the maximum number of results in a single query. This value must be a number between 1 and 50.
// Provide a limit parameter
$options = array(
'limit' => 20
);offset ( number ) [ optional ]: this will start the result list at the provided value and will give limit number of results. This value must be 0 or greater.
// Provide an offset parameter
$options = array(
'offset' => 5
);where ( string | array ) [ optional ]: Filters are used to swift through results to get what you want. You can exclude and include results based on their properties. For example you could remove all Games where the rating was below 80 (where rating >= 80).
Note: in the old (v2) IGDB API this field was called
filter.
If you provide the filter parameters as an array, you must have three values in it with the following indexes:
field: The name of the field you want to apply the filter topostfix: The postfix you want to use with the filter. Refer to the IGDB Filters Documentation for available postfixes.value: The value of the filter.
// Provide a single filter rule as an array
// In this case you must have field, postfix and value elements in the array
$options = array(
'field' => 'release_dates.platform',
'postfix' => '=',
'value' => 8
);
// Provide multiple filter rules as an array
// In this case you must have field, postfix and value elements in the arrays
$options = array(
array(
'field' => 'release_dates.platform',
'postfix' => '=',
'value' => 8
),
array(
'field' => 'total_rating',
'postfix' => '>=',
'value' => 70
)
);You can provide the filter parameter as string. In this case you can pass the string with apicalypse string:
// Provide a single filter rule as a string
$options = array(
'where' => 'release_dates.platform = 8'
);Or you can provide multiple criteria as an array with apicalypse syntax:
$options = array(
'fields' => 'id, name, platforms, genres', // we want to see these fields in the result
'where' => array( // make sure to have each criteria as a separate element in the array
'release_dates.platform = 8', // and separate field names, postfixes and values with space
'total_rating >= 70',
'genres = 4'
)
);In this case make sure to separate the field name, the postfix and the value with spaces!
sort ( string | array ) [ optional ]: sorting (ordering) is used to order results by a specific field.
Note: in the old (v2) IGDB API this field was called
order.
IF you provide the Order parameter as an array, you must have two values in it with the following indexes:
field: The field you want to do the ordering bydirection: The direction of the ordering. It must be eitherascfor ascending ordescfor descending ordering.
// Provide an sort parameter as an array
$options = array(
'sort' => array(
'field' => 'release_dates.date',
'direction' => 'desc',
)
);You can also provide the sort parameter as string. In this case you can pass the string with apycalipse syntax:
// Provide an order parameter as a string
$options = array(
'sort' => 'release_dates.date desc'
);public IGDB::close_handler ( ) : void
You can close the CURL session handler manually if you need to. The class will not do it by itself after any query in case you need to start several queries. After closing the session you will not be able to start new query with the actual instance of the class.
public IGDB::reinit_handler ( ) : void
After you closed the CURL session manually with IGDB::close_handler() than you will not be able to run any query against IGDB with the current instance of the class. However, if you need to run a query again, just call this method, and the CURL handler will be reinitialized.
public IGDB::apicalypse( $options ) : string
You can convert the options array to IGDB's query language called Apicalypse. This method will return a string with the parsed parameters. You can read additional informations in the IGDB Apicalypse Documentation
Parameters
$options: the options array to convert
Return
The method returns the query string with apicalypse syntax.public IGDB::get_request_info ( ) : array
If you need detailed information regarding the latest query, you can get it by this method. It returns the return value of curl_getinfo() php function.
public IGDB::api_status ( ) : array
The API Status endpoint is a way to see a usage report for an API key. It shows stats such as requests made in the current period and when that period ends. Requests to this endpoint does not count towards you monthly request limit, however this endpoint is not intended to be requested repeatedly before every request to other endpoints, but rather be used more sparingly. Therefore this endpoint is rate limited to 5 requests per minute. Exceeding this limit will suspend your access to THIS endpoint for 1 hour. If you have exceeded the limit and make another request you will receive a response with status code 429 ‘Too many requests’.
private IGDB::_init_curl ( ) : void
This method creates the CURL session and sets a few additional configuration to it.
private IGDB::_exec_query ( string $endpoint, array $options ) : array - This method will start the query against IGDB. Returns the JSON decoded response from IGDB as an array.
Parameters
$endpoint ( string ): url of the endpoint to execute the query against$options ( array ): the options array
Return
The method returns the IGDB response as an array.
private IGDB::_construct_url( string $endpoint, boolean $count = false) : string - The method will construct the full URL for the request and will return the constructed URL as a string.
Parameters
$endpoint ( string ): the endpoint to use$count ( boolean ): whether the request should return the number of matches instead of the actual resultset
Return
This method will return the full constructed URL to the IGDB Endpoint as a string.
Every endpoint method takes an $options array as a parameter to set up the query (check the Options Parameters Section for more details about the available parameters and values). As a second optional parameter you can pass a boolean $count.
These methods are returning an array with objects decoded from IGDB response JSON by default. If you provide boolean true as a second parameter, it will execute a count query against the selected endpoint which will return an object with a count property holding the sum of the found items. You can filter the results with the $options array.
Exceptions are thrown in any case of error.
Refer to the Return Values Section for more details about the return values of these methods.
Parameters
$options ( array ): The options array$count (boolean) [optional]: Whether you want to get the found items or the sum of them. If this value istruethen the result count will be returned. By default this isfalse.
Return
If $count parameter is set to true the number of items will be returned. Otherwise the IGDB response as an array.
public IGDB::achievement ( array $options, boolean $count = false ) : array | object
Fetch data using Achievement endpoint.
public IGDB::achievement_icon ( array $options, boolean $count = false ) : array | object
Fetch data using Achievement Icon endpoint.
public IGDB::age_rating ( array $options, boolean $count = false ) : array | object
Fetch data using Age Rating endpoint.
public IGDB::age_rating_content_description ( array $options, boolean $count = false ) : array | object
Fetch data using Age Rating Content Description endpoint.
public IGDB::alternative_name ( array $options, boolean $count = false ) : array | object
Fetch data using Alternative Name endpoint.
public IGDB::artwork ( array $options, boolean $count = false ) : array | object
Fetch data using Artwork endpoint.
public IGDB::character ( array $options, boolean $count = false ) : array | object
Fetch data using Character endpoint.
public IGDB::character_mug_shot ( array $options, boolean $count = false ) : array | object
Fetch data using Character Mug Shot endpoint.
public IGDB::collection ( array $options, boolean $count = false ) : array | object
Fetch data using Collection endpoint.
public IGDB::company ( array $options, boolean $count = false ) : array | object
Fetch data using Company endpoint.
public IGDB::company_logo ( array $options, boolean $count = false ) : array | object
Fetch data using Company Logo endpoint.
public IGDB::company_website ( array $options, boolean $count = false ) : array | object
Fetch data using Company Website endpoint.
public IGDB::cover ( array $options, boolean $count = false ) : array | object
Fetch data using Cover endpoint.
public IGDB::external_game ( array $options, boolean $count = false ) : array | object
Fetch data using External Game endpoint.
public IGDB::feed ( array $options, boolean $count = false ) : array | object
Fetch data using Feed endpoint.
public IGDB::feed_follow ( array $options, boolean $count = false ) : array | object
Fetch data using Feed Follow endpoint.
public IGDB::follow ( array $options, boolean $count = false ) : array | object
Fetch data using Follow endpoint.
public IGDB::franchise ( array $options, boolean $count = false ) : array | object
Fetch data using Franchise endpoint.
public IGDB::game ( array $options, boolean $count = false ) : array | object
Fetch data using Game endpoint.
public IGDB::game_engine ( array $options, boolean $count = false ) : array | object
Fetch data using Game Engine endpoint.
public IGDB::game_engine_logo ( array $options, boolean $count = false ) : array | object
Fetch data using Game Engine Logo endpoint.
public IGDB::game_mode ( array $options, boolean $count = false ) : array | object
Fetch data using Game Mode endpoint.
public IGDB::game_version ( array $options, boolean $count = false ) : array | object
Fetch data using Game Version endpoint.
public IGDB::game_version_feature ( array $options, boolean $count = false ) : array | object
Fetch data using Game Version Feature endpoint.
public IGDB::game_version_feature_value ( array $options, boolean $count = false ) : array | object
Fetch data using Game Version Feature Value endpoint.
public IGDB::game_video ( array $options, boolean $count = false ) : array | object
Fetch data using Game Video endpoint.
public IGDB::genre ( array $options, boolean $count = false ) : array | object
Fetch data using Genre endpoint.
public IGDB::involved_company ( array $options, boolean $count = false ) : array | object
Fetch data using Involved Company endpoint.
public IGDB::keyword ( array $options, boolean $count = false ) : array | object
Fetch data using Keyword endpoint.
public IGDB::list ( array $options, boolean $count = false ) : array | object
Fetch data using List endpoint.
public IGDB::list_entry ( array $options, boolean $count = false ) : array | object
Fetch data using List Entry endpoint.
public IGDB::multiplayer_mode ( array $options, boolean $count = false ) : array | object
Fetch data using Multiplayer Mode endpoint.
public IGDB::page ( array $options, boolean $count = false ) : array | object
Fetch data using Page endpoint.
public IGDB::page_background ( array $options, boolean $count = false ) : array | object
Fetch data using Page Background endpoint.
public IGDB::page_logo ( array $options, boolean $count = false ) : array | object
Fetch data using Page Logo endpoint.
public IGDB::page_website ( array $options, boolean $count = false ) : array | object
Fetch data using Page Website endpoint.
public IGDB::platform ( array $options, boolean $count = false ) : array | object
Fetch data using Platform endpoint.
public IGDB::platform_logo ( array $options, boolean $count = false ) : array | object
Fetch data using Platform Logo endpoint.
public IGDB::platform_version ( array $options, boolean $count = false ) : array | object
Fetch data using Platform Version endpoint.
public IGDB::platform_version_company ( array $options, boolean $count = false ) : array | object
Fetch data using Platform Version Company endpoint.
public IGDB::platform_version_release_date ( array $options, boolean $count = false ) : array | object
Fetch data using Platform Version Release Date endpoint.
public IGDB::platform_website ( array $options, boolean $count = false ) : array | object
Fetch data using Platform Website endpoint.
public IGDB::player_perspective ( array $options, boolean $count = false ) : array | object
Fetch data using Player Perspective endpoint.
public IGDB::product_family ( array $options, boolean $count = false ) : array | object
Fetch data using Product Family endpoint.
public IGDB::pulse ( array $options, boolean $count = false ) : array | object
Fetch data using Pulse endpoint.
public IGDB::pulse_group ( array $options, boolean $count = false ) : array | object
Fetch data using Pulse Group endpoint.
public IGDB::pulse_source ( array $options, boolean $count = false ) : array | object
Fetch data using Pulse Source endpoint.
public IGDB::pulse_url ( array $options, boolean $count = false ) : array | object
Fetch data using Pulse Url endpoint.
public IGDB::rate ( array $options, boolean $count = false ) : array | object
Fetch data using Rate endpoint.
public IGDB::release_date ( array $options, boolean $count = false ) : array | object
Fetch data using Release Date endpoint.
public IGDB::review ( array $options, boolean $count = false ) : array | object
Fetch data using Review endpoint.
public IGDB::review_video ( array $options, boolean $count = false ) : array | object
Fetch data using Review Video endpoint.
public IGDB::screenshot ( array $options, boolean $count = false ) : array | object
Fetch data using Screenshot endpoint.
public IGDB::search ( array $options, boolean $count = false ) : array | object
Fetch data using Search endpoint.
public IGDB::theme ( array $options, boolean $count = false ) : array | object
Fetch data using Theme endpoint.
public IGDB::time_to_beat ( array $options, boolean $count = false ) : array | object
Fetch data using Time To Beat endpoint.
public IGDB::title ( array $options, boolean $count = false ) : array | object
Fetch data using Title endpoint.
public IGDB::website ( array $options, boolean $count = false ) : array | object
Fetch data using Website endpoint.
Let's do a simple example. Get the third page of a game list, where the game we are looking for is LIKE "uncharted" (this example is available in examples/_basic_example.php)
<?php
require '../src/class.igdb.php';
// Instantiate the class
$IGDB = new IGDB('<YOUR API KEY>');
// Setting up the query parameters
$options = array(
'search' => 'uncharted', // searching for games LIKE uncharted
'fields' => array( // we want to see these values in the results
'id',
'name',
'cover'
),
'limit' => 5, // we only need maximum 5 results per query (pagination)
'offset' => 10 // we would like to show the third page; fetch the results from the tenth element (pagination)
);
try {
// Running the query against IGDB; passing the options parameter
$result = $IGDB->game($options);
// Showing the result
var_dump($result);
} catch (Exception $e) {
// Catching Exceptions, if there is any
echo $e->getMessage();
}
?>Every Endpoint Method can return two different type of results, depending on the second parameter provided for them:
-
By default the second
$countparameter is booleanfalse. this means, that the query will be ran against the IGDB, returning a$resultarray.// This will return an array with the results $IGDB->game($options);
-
If you pass a boolean
trueas a second parameter, then you will get an object with acountproperty containing the item count from the selected endpoint.// This will return an object with a count public property $IGDB->game($options, true);
-
The result object's properties will vary depending on the provided field list in the
optionsarray. Let's see what is the result of the above example query:array (size=5) 0 => object(stdClass)[2] public 'id' => int 14441 public 'cover' => int 22383 public 'name' => string 'Uncharted Waters 2' (length=18) 1 => object(stdClass)[3] public 'id' => int 998 public 'cover' => int 86364 public 'name' => string 'Uncharted: Golden Abyss' (length=23) 2 => object(stdClass)[4] public 'id' => int 125062 public 'cover' => int 83686 public 'name' => string 'Uncharted Ocean: Set Sail' (length=25) 3 => object(stdClass)[5] public 'id' => int 35788 public 'cover' => int 71621 public 'name' => string 'Abyss Raiders: Uncharted' (length=24) 4 => object(stdClass)[6] public 'id' => int 19583 public 'cover' => int 15883 public 'name' => string 'Uncharted: Fight for Fortune' (length=28)
As you can see, the
$resultvariable holds an array, containing 5 elements (thelimitparameter is set to 5), and these elements are on the third page of the results (offsetis set to 10). Every element of the$resultarray is an object, containing properties called like the fields from optionsfieldsparameter.
Please note, that sometimes there are records which are missing one or more fields.
Refer to the IGDB's respective endpoint documentation regarding the mandatory fields.
Working with non-mandatory fileds requires you to check for availability before accessing them.
- When the
$countproperty is set totrue, the return value will be an object with a publiccountproperty:This value will hold the number of matches in IGDB database filtered by the passedobject(stdClass)[2] public 'count' => int 40
$options.
- Fixing inaccurate information in the Readme
- Minor changes / fixes in the Readme
- Added method
_construct_url - Updated every endpoint method to construct the endpoint url's different
- IGDB Api v3 compatibility update
- Removed
expanderparameter - Renamed parameter
filtertowhere - Renamed parameter
ordertosort - Removed multiple methods:
_stringify_options_construct_urlcountcustom_query
- Added method
apicalypse - Added method
api_status - Updated every endpoint method (removed
$execute, added$count)
- Fixed a bug at the request's error handling
public IGDB::get_request_info()public method added
- Default properties has been removed.
- set_default public method has been removed.
- Providing either search or id parameter in the options array are not mandatory anymore.
- Providing fields parameter when using expander is not mandatory anymore.
- Ordering parameter 'order' in the options array has been renamed to 'direction'. Refer to the order section of the options parameters.
- Implemented count method. Refer to the count section of the Readme.
- Example count.php has been added.
- Updated Readme
- Modified the constructor to ask only for the API Key. The API URL has been changed to be fix for every user (by IGDB).
- The API URL and KEY setter and getter methods has been removed.
- The API URL and KEY validator methods has been removed.
- New method for order parameter constructing has been implemented.
- Stringify Options method is private again. Use the updated endpoint methods instead.
- Updated Endpoint Methods to accept a second optional parameter to return the constructed URL instead of executing the query.
- basic.php example file has been renamed to basic.example.php.
- order.php example has been added.
- order_subfilter.php example has been added.
- All example files has been modified with the updated constructor.
- Added Changes section to the ReadMe.
- Fixed filter parameter constructing; the parameter input has been changed.
- Added example snippets to the Options Parameters section.
- Added example file filter_multiple_criteria.php
- Added example file filter_single_criteria.php