README

简介

本软件包是用于检索游戏信息的 IGDB 版本 4 API 的 PHP 包装器。它包含以下内容：

• 所有 IGDB v4 端点
• 用于获取访问令牌的认证包
• 高级查询构建器

系统要求

需要 PHP 8.0 或更高版本；建议尽可能使用最新的 PHP 版本。

安装

运行以下命令以安装此软件包

$ composer require kris-kuiper/igdbv4

认证

要使用 IGDB API，您必须拥有客户端 ID 和访问令牌。有关获取这些信息的完整信息，请参阅 https://dev.twitch.tv/docs/authentication。

但是，为了立即开始

• 在 Twitch 上注册一个免费账号
• 注册您的应用程序
• 管理您新创建的应用程序
• 通过点击 [新建密钥] 生成客户端密钥
• 注意客户端 ID 和客户端密钥

当您获得客户端 ID 和客户端密钥后，可以使用 Authentication 类获取访问令牌。

获取访问令牌的示例

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

注意：访问令牌的有效期约为 60 天。建议保存访问令牌和过期时间以供以后使用，因此不需要为每次请求生成新的访问令牌。

端点

列表中的每个端点都可以通过调用端点名称进行请求，并且具有以下方法

• findById() - 通过其标识符查找项（例如，通过 ID 查找游戏）
• list() - 返回项列表（例如，列出特定游戏的全部截图）
• query() - 在当前端点上执行原始查询（例如，执行自定义查询以查找特定类型）

只有游戏、平台、收藏、角色和主题端点也支持 search() 方法。

以下是一个支持端点的列表。

获取游戏、平台和类型的示例

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;');

注意：所有列出的端点都可通过 IGDB 类获取。

高级查询构建器

查询构建器允许您以编程方式创建查询，您可以使用 query() 方法在调用每个端点时使用这些查询。

它包含以下方法

• fields()（选择特定字段）
• exclude()（排除特定字段）
• search()
• where()（where、whereIn 和分组 where）
• orWhere()（仅在有 where 的情况下）
• sort()
• offset()
• limit()

使用 "games" 端点使用查询构建器的示例

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);

使用查询构建器的示例

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();

查询构建器的高级 where 条件

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();

运行单元测试

在您的环境中安装 phpunit 并运行

$ php ./vendor/bin/phpunit

问题和反馈

手册中未解决的问题应提交到上述链接的相关存储库。

如果您在此版本中发现代码表现异常或与其文档描述的行为不符，请创建一个相关存储库的问题，如上述链接。

许可

您可以在以下链接找到本许可证的副本：LICENSE.md。