README

Germania KG · JsonAPI 客户端

支持缓存的服务端PHP包装器，用于从德国的JSON API进行简单检索。

安装

$ composer require germania-kg/jsonapi-client

用法

使用 Guzzle 工厂

JsonApiClient 需要 Guzzle 客户端 来执行API请求。您可以选择提供自己的Guzzle实例或使用 GuzzleFactory，这对于需要“bearer” 访问令牌 的 API端点 很有用。

<?php
use Germania\JsonApiClient\GuzzleFactory;

// Have your Web API endpoint and Access token at hand
$api = "https://api.example.com/"
$token = "manymanyletters"; 

// Setup a Guzzle Client that will ask the Web API
$guzzle = (new GuzzleFactory)( $api, $token);

JsonApiClient

JsonApiClient 需要上述 Guzzle 客户端 以及一个 PSR-6 缓存项池。它可选地接受一个 PSR-3 记录器 和/或一个PSR-3 日志级别名称 用于错误。

<?php
use Germania\JsonApiClient\JsonApiClient;
use Germania\JsonApiClient\GuzzleFactory;
use GuzzleHttp\Client;

$guzzle = new Client( ... );
$guzzle = (new GuzzleFactory)( $api, $token);

$cache  = new \Stash\Pool( ... );
$logger = new \Monolog\Logger( ... );

$api_client = new JsonApiClient($guzzle, $cache );
$api_client = new JsonApiClient($guzzle, $cache, $logger );
$api_client = new JsonApiClient($guzzle, $cache, $logger, "alert" );

自定义

错误日志级别：当Guzzle失败时使用的日志级别名称。默认为 error。

$api_client->error_loglevel = "error";

请求方法：此库是为GET构建的，并不打算或测试POST、DELETE等。

$api_client->request_method = "GET";

缓存生命周期：缓存生命周期将来自API响应，并回退到此值

$api_client->cache_lifetime_default = 3600;

安全考虑：缓存引擎

结果存储在传递给 JsonApiClient 构造函数的PSR-6缓存中，使用 缓存键 来查找下一次的结果。

此 缓存键 包含一个快速计算的 sha256散列，该散列对应于授权头。缺点是，您的认证令牌容易受到 散列碰撞 攻击，即两个不同的字符串产生相同的散列。

希望认证令牌有一个内置的生命周期。一旦这个生命周期达到，认证令牌就毫无价值了。此外，当攻击者能够访问您的缓存文件时，他将拥有所有结果，无论他是否拥有您的认证令牌。

安全提示

考虑传递一个“始终为空缓存”或具有非常短生命周期的缓存，例如 Stash的Ephemeral 驱动器。
安全地存储您的缓存。这不是本库的责任。
经常清理项目缓存。这不是本库的责任。

检索数据

JsonApiClient 类是可调用的；使用URL路径和可选的过滤器值数组调用它返回一个包含API提供的文档的 ArrayIterator。

缓存：结果缓存在给定的 PSR-6 缓存项池 中。缓存项TTL取决于随 Guzzle 客户端 请求一起返回的 Cache-Control: max-age=SECONDS 头。默认TTL为3600秒。

$items = $downloads_client("some/url/path");

foreach( $items as $item):
	print_r( $item );
endforeach;

示例记录

使用 print_r( $item ) 可能会显示类似以下内容

Array (
    [company] => ACME Corp.
    [brand] => ACME's Best
    [title] => ACME Super Thingy
    ...
)

过滤结果

为了缩小结果范围，all 和 latest 方法都接受一个带有过滤器值的数组。过滤器值可以包含多个值，用逗号分隔。

将过滤器数组项视为 WHERE … AND… 子句，并将逗号分隔的值视为 'a' OR 'b'

$filters = array(
  'company' => "ACME",
  'category' => "brochure",
  'language' => "en"
);

$items = $downloads_client("some/url/path", $filters);

错误和异常

在ask-cache / 请求 / 响应 / 结果构建阶段发生的任何错误或异常首先被记录到构造函数中传递的PSR-3记录器。捕获的错误将被重新抛出为 JsonApiClientExceptionInterface 异常实例。

<?php
use Germania\JsonApiClient\JsonApiClientExceptionInterface;

use Germania\JsonApiClient\{
  JsonApiClientCacheException,
  JsonApiClientRequestException,
  JsonApiClientResponseException,
  JsonApiClientResultsException
};

缓存问题

在实际发送请求之前，会询问Cache ItemPool。如果发生任何错误，将抛出JsonApiClientCacheException。此类实现了JsonApiClientExceptionInterface并扩展了\RuntimeException。

请求问题

当JsonApiClient捕获到Guzzle RequestException或TransferExceptions，即请求或服务器出现问题时，将抛出JsonApiClientRequestException。此类实现了JsonApiClientExceptionInterface并扩展了\RuntimeException。

响应问题

预期的响应应该是一个有效的JsonAPI响应。每当响应无法解码为有用的数组时，将抛出JsonApiClientResponseException。此类实现了JsonApiClientExceptionInterface并扩展了\UnexpectedValueException。

结果构建问题

在构建结果数组或写入缓存时出现问题时，将抛出JsonApiClientResultsException。此类实现了JsonApiClientExceptionInterface并扩展了\RuntimeException。

开发和单元测试

$ git clone https://github.com/GermaniaKG/jsonapi-client-php.git
$ cd jsonapi-client-php
$ composer install

单元测试

将phpunit.xml.dist复制到phpunit.xml，并调整API_BASE_URL和AUTH_TOKEN环境变量。然后像这样运行PhpUnit

$ composer test
# or
$ vendor/bin/phpunit

germania-kg / jsonapi-client

维护者

详情