README

IgdbApiBundle

此包提供了一种与 Internet Game Database API 通信的简单方法。您可以通过拉取请求为项目做出贡献。

安装

先决条件

IGDB 的账户和密钥。注册。
PHP 7.1.3 或更高版本
Symfony 3.4 或更高版本。只需要 3 个核心包（不是整个框架）
- symfony/config: ^3.4|^4.0
- symfony/dependency-injection: ^3.4|^4.0
- symfony/http-kernel: ^3.4|^4.0)
Guzzle 6.3 或更高版本

Symfony 包和 Guzzle 会由 composer 自动包含。

Composer

要使用 Composer 获取包的最新版本，请运行以下命令

composer require emanuilnikolov/igdb-api-bundle

配置

没有 Symfony Flex

在 app/AppKernel.php 中启用此包

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = [
            // ...
            new EN\IgdbApiBundle\ENIgdbApiBundle(),
        ];

        // ...
    }
}

将以下内容复制到您的 app/config/config.yml 文件中

# app/config/config.yml
en_igdb_api:
    base_url: '%env(YOUR_BASE_URL)%'
    api_key: '%env(YOUR_API_KEY)%'

并更新您的 .env 文件

...
###> emanuilnikolov/igdb-api-bundle ###
YOUR_BASE_URL=
YOUR_API_KEY=
###< emanuilnikolov/igdb-api-bundle ###
...

使用 Symfony Flex

此包有一个 Flex 脚本，它将自动将 en_igdb_api.yaml 添加到您的 config/packages 目录，并相应地更新您的 .env 文件。

使用您的凭据

在 .env 文件中分配 YOUR_BASE_URL 和 YOUR_API_KEY，这些凭据可以在 IGDB API 的主页找到（您必须登录）。

如果您不想使用环境变量（强烈推荐），您可以替换 '%env(YOUR_BASE_URL)%' 和 '%env(YOUR_API_KEY)%'。

使用

可用的服务

包装器
- 服务 ID - en_igdb_api.wrapper
- 别名
  - IgdbWrapper
  - IgdbWrapperInterface
参数构建器
- 服务 ID - en_igdb_api.parameter.builder
- 别名
  - ParameterBuilder
  - ParameterBuilderInterface
参数集合
- 服务 ID - en_igdb_api.parameter.collection
- 别名
  - AbstractParameterCollection

初始化

这些服务与其他 Symfony 服务一样通过构造函数注入、控制器动作方法等方式进行初始化。

示例

// src/Controller/IgdbController.php
namespace App\Controller;

// ...
use EN\IgdbApiBundle\Igdb\IgdbWrapperInterface;
use EN\IgdbApiBundle\Igdb\Parameter\ParameterBuilderInterface;

class IgdbController extends AbstractController
{
    /**
     * @Route("/index", name="index")
     */
    public function index(IgdbWrapperInterface $wrapper, ParameterBuilderInterface $builder)
    {
        $builder->setId(1);
        $games = $wrapper->games($builder);
        // ...
    }
}

为了提高灵活性，建议对所需服务的接口进行类型提示，而不是实际实现。

参数构建器

构建器用于构建将要发送到 API 的查询字符串。它使用方法链来收集参数值。在调用 buildQueryString() 方法（包装器中自动执行）后，它们将被组合成一个查询字符串。可用的参数在此处列出这里。它们作为 ParameterBuilder 中的方法可用，并可以按以下方式链接

示例

// src/Controller/IgdbController.php
// ...
 
/**
* @Route("/index", name="index")
*/
public function index(IgdbWrapperInterface $wrapper, ParameterBuilderInterface $builder)
{
    $builder
      ->setLimit(33)
      ->setOffset(22)
      ->setFilters("[rating][gte]", "80");
    //...
}

提示

如果未明确定义，则 fields 参数的默认值为 '*'。
使用 setIds() 方法设置多个逗号分隔的 id：setIds("1,2,3")。
buildQueryString() 方法将之前在构建器中设置的参数合并成一个查询字符串。在执行上述示例时，将返回 1?fields=*&limit=33&offset=22。

参数集合

扩展AbstractParameterCollection提供了一种存储ParameterBuilder频繁使用的配置的方法，从而将其与逻辑的其他部分解耦。

示例

创建您的自定义集合并扩展AbstractParameterCollection

// src/Igdb/Collection/CustomCollection.php
namespace EN\IgdbApiBundle\Tests\Igdb\Parameter;

use EN\IgdbApiBundle\Igdb\Parameter\AbstractParameterCollection;

class CustomCollection extends AbstractParameterCollection
{

    public function customMethod()
    {
        return $this->builder
            ->setIds("4,5,6")
            ->setOrder("popularity:desc");
    }
}

然后，可以使用IgdbWrapper获取所需的集合

// src/Controller/IgdbController.php
// ...

/**
* @Route("/index", name="index")
*/
public function index(IgdbWrapperInterface $wrapper)
{
    $customCollection = $wrapper->getParameterCollection(CustomCollection::class);
    $builder = $customCollection->customMethod();
    // ...
}

包装器

端点

API文档中描述的端点可作为IgdbWrapper中的方法使用。所有这些方法都接受ParameterBuilder的实例，并返回一个包含数据的PHP关联数组。此扩展利用了PSR-7标准

示例

// src/Controller/IgdbController.php
// ...
 
/**
* @Route("/index", name="index")
*/
public function index(IgdbWrapperInterface $wrapper, ParameterBuilderInterface $builder)
{
    // Fetching games from the API
    $builder
      ->setLimit(1)
      ->setFields("id,name");
    
    $games = $wrapper->games($builder);
    
    // Running var_dump on $games will output:
    // array (size=1)
    //   0 => 
    //     array (size=2)
    //       'id' => int 77207
    //       'name' => string 'Dune: The Battle for Arrakis' (length=28)
    
    // After the execution of any endpoint method, the response of the API is recorded in the wrapper 
    // and can be accessed with the getResponse() method.
    $response = $wrapper->getResponse();
    
    // The response implements the PSR-7 interface.
    class_implements($response); // This will return "Psr\Http\Message\ResponseInterface".
    //...
}

私有端点

这些将在扩展的下一个版本中介绍。

滚动API

这是IGDB API提供的一种提供更简单、更快的分页结果的方法。您可以在这里了解更多信息。

示例

// src/Controller/IgdbController.php
// ...
 
/**
* @Route("/index", name="index")
*/
public function index(IgdbWrapperInterface $wrapper, ParameterBuilderInterface $builder)
{
    // This will limit the result set to 10 games and enable the scroll functionality.
    $builder->setLimit(10)->setScroll(1);
    
    // The API will return 10 games and the scroll headers (X-Next-Page & X-Count).
    $gamesSetOne = $wrapper->games($builder);
    
    // The X-Next-Page header is accessed with the getScrollNextPage() method.
    // The most recent response is automatically used and can be omitted.
    $scrollNextPageUrl = $wrapper->getScrollNextPage();
    
    // The most recent received response is accessed with the getResponse() method.
    $response = $wrapper->getResponse(); 
    
    // and can be manually passed in.
    // The X-Count header is accessed with the getScrollCount() method.
    $scrollCount = $wrapper->getScrollCount($response);
    
    // scroll() will use the provided URL from getScrollNextPage() to get the next result set.                                          
    $gamesSetTwo = $wrapper->scroll($scrollNextPageUrl); 
    
    // The API will always send the same URL so you can repeatedly query the same URL to get the next result set.
    $gamesSetThree = $wrapper->scroll($scrollNextPageUrl);
    
    // ...
}

搜索

搜索是通过使用IgdbWrapper的search()方法或通过设置ParameterBuilder的setSearch()方法来完成的。

// src/Controller/IgdbController.php
namespace App\Controller;

// ...
use EN\IgdbApiBundle\Igdb\IgdbWrapperInterface;
use EN\IgdbApiBundle\Igdb\Parameter\ParameterBuilderInterface;
use EN\IgdbApiBundle\Igdb\ValidEndpoints;

class IgdbController extends AbstractController
{
    /**
     * @Route("/index", name="index")
     */
    public function index(IgdbWrapperInterface $wrapper, ParameterBuilderInterface $builder)
    {
        // The second argument is the endpoint that will be called. 
        // All of the API's endpoints are available as constants in the ValidEndpoints class.
        $games = $wrapper->search("Mass Effect", ValidEndpoints::FRANCHISES, $builder);
        
        // This will produce the same as the former.
        $builder->setSearch("Mass Effect");
        $games = $wrapper->franchises($builder);
        // ...
    }
}

其他有用的方法

以下所有方法（除fetchDataAsJson()外）都由端点方法内部使用。

`fetchData()`

此方法位于每个端点方法之后，可以独立使用。

// Accepts the endpoint's name and an instance of the ParameterBuilder as its arguments.
$games = $wrapper->fetchData(ValidEndpoints::GAMES, $builder);

`fetchDataAsJson()`

与fetchData()相同，但将API的原始JSON响应作为字符串返回，而不是PHP关联数组。

$charactersJson = $wrapper->fetchDataAsJson(ValidEndpoints::CHARACTERS, $builder);

`sendRequest()`

向给定的URL发送HTTP请求。此方法将IgdbWrapper的$response属性赋值。通过遵守在4xx或5xx错误发生时不抛出异常的良好做法来修改Guzzle的request()方法的行为。

$response = $wrapper->sendRequest("https://api-endpoint.igdb.com/non-existant"); // This will produce a 404 status code.

// Because the $response implements the PSR-7 standart and Guzzle is prevented from throwing an exception
// you have more flexibility for error handling.
$statusCode = $response->getStatusCode(); // Get the status code.
$reasonPhrase = $response->getReasonPhrase(); // Get the reason phrase.
$headers = $response->getHeaders(); // Get the response's headers.

您可以在这里了解更多有关$response的可用方法。

`processResponse()`

使用json_decode()函数将提供的响应体解码为PHP关联数组。如果API返回不支持json_decode()的数据类型，它仍然包含在数组中。

$response = $wrapper->getResponse;
$resultSet = $wrapper->processResponse($response);

`getEndpoint()`

结合基本URL和端点。

$url = $wrapper->getEndpoint(ValidEndpoints::ACHIEVEMENTS); // "https://api-endpoint.igdb.com/achievements/"

emanuilnikolov / igdb-api-bundle

维护者

详细信息