README

此 Web API 客户端库由 Pathfinder 使用，并处理所有 ESI API 请求。
可以轻松添加其他 API，并且可以与它们自己的配置并行使用。包括以下客户端

• CCP ESI API 客户端： Esi.php
• CCP SSO API 客户端： Sso.php
• GitHub 基本API客户端： GitHub.php
• eve-scout "Thera" API 客户端： EveScout.php

此 Web 客户端基于 Guzzle 构建，并大量使用 Guzzle 内置的 中间件 概念。

安装

使用 Composer 进行安装。在 composer.json 的 require 部分添加

{
  "require": {
    "php-64bit": ">=7.2",
    "exodus4d/pathfinder_esi": "v2.0.0"
  }
}

Pathfinder: 此 Web API 客户端库将与 Pathfinder 项目所需的所有其他依赖项自动通过 Composer 安装。（→参见 composer.json）。

Pathfinder 的新版本可能也需要此存储库的新版本。因此，在更新 Pathfinder 后运行 composer install 将升级/安装新的 ESI 客户端。有关更多信息，请查看 Pathfinder 的 发布说明。

使用客户端

1. 初始化客户端

// New web client instance for GitHub API [→ Github() implements ApiInterface()]
$client = new \Exodus4D\ESI\Client\GitHub\GitHub('https://api.github.com');

// configure client [→ check ApiInterface() for methods]
$client->setTimeout(3);                     // Timeout of the request (seconds)
$client->setUserAgent('My Example App');    // User-Agent Header (string)
$client->setDecodeContent('gzip, deflate'); // Accept-Encoding Header
$client->setDebugLevel(3);                  // Debug level [0-3]
$client->setNewLog(function() : \Closure {  // Callback for new LogInterface
   return function(string $action, string $level = 'warning') : logging\LogInterface {
       $log = new logging\ApiLog($action, $level);
       $log->addHandler('stream', 'json', './logs/requests.log');
       return $log;
   };
});

// Loggable $requests (e.g. HTTP 5xx resp.) will not get logged if return false;
$client->setIsLoggable(function() : \Closure {
    return function(RequestInterface $request) use ($f3) : bool {
        return true;
    };
});

$client->setLogStats(true);                 // add some cURL status information (e.g. transferTime) to logged responses

$client->setLogCache(true);                 // add (local) cache info (e.g. response data cached) to logged requests
$client->setLogAllStatus(false);            // log all requests regardless of response HTTP status code
$client->setLogRequestHeaders(false);       // add request HTTP headers to loggable requests
$client->setLogResponseHeaders(false);      // add response HTTP headers to loggable requests
$client->setLogFile('requests');            // log file name for request/response errors
$client->setRetryLogFile('retry_requests'); // log file for requests errors due to max request retry exceeds

$client->setCacheDebug(true);               // add debug HTTP Header with local cache status information (HIT/MISS)
$client->setCachePool(function() : \Closure {
    return function() : ?CacheItemPoolInterface {
        $client = new \Redis();             // Cache backend used accross the web client
        $client->connect('localhost', 6379);
          
        // → more PSR-6 compatible adapters at www.php-cache.com (e.g. Filesystem, Array,…)
        $poolRedis = new RedisCachePool($client);
        $cachePool = new NamespacedCachePool($poolRedis, 'myCachePoolName');
        return $cachePool;                  // This can be any PSR-6 compatible instance of CacheItemPoolInterface()
    };
});

2. 发送请求

// get all releases from GitHub for a repo
$releases = $client->send('getProjectReleases', 'exodus4d/pathfinder');
// … more requests here

概念

Guzzle 中间件

中间件类是 小 函数，它们 钩入 到 Guzzle 中的 "请求 → 响应" 链。

• 中间件可以 操作 请求和响应对象
• 每个中间件都专注于处理自己的任务。
• 已预配置了 "日志记录"、"缓存" 等中间件。
• 每个中间件都有自己的配置选项，可以通过 $client-> 设置。
• 所有配置的中间件都推入一个 HandlerStack()，该堆栈针对每个请求进行 解析。
• 在 HandlerStack() 中的 顺序 是至关重要的！

Guzzle HandlerStack

此流程图显示了 ESI.php API 客户端使用的所有中间件。对 ESI API 的每个请求都按照以下 顺序 调用所有中间件

请求前

GuzzleJsonMiddleware → GuzzleLogMiddleware → GuzzleCacheMiddleware → GuzzleCcpLogMiddleware → GuzzleRetryMiddleware → GuzzleCcpErrorLimitMiddleware

响应后（→ 逆序！）

GuzzleCcpErrorLimitMiddleware → GuzzleRetryMiddleware → GuzzleCcpLogMiddleware → GuzzleCacheMiddleware → GuzzleLogMiddleware → GuzzleJsonMiddleware

默认 中间件

JSON

期望有 JSON 编码 响应 数据的请求在 HandlerStack 中有 GuzzleJsonMiddleware。
这会在 request 中添加 Accept: application/json 标头，并将 response 体的内容包装到 JsonStream 中。

$client->setAcceptType('json');

缓存

客户端实例应设置一个兼容 PSR-6 的缓存池，其中可以存储 持久 数据。有效的 response 数据可以通过其 Cache-Expire HTTP 标头进行缓存。 GuzzleCacheMiddleware 还处理 Etag 标头。其他 中间件 也可以根据需要访问缓存池。例如，GuzzleLogMiddleware 可以通过使用缓存池中的错误计数来 限制 错误日志记录等。

→ 查看：$client->setCachePool();

提示：请访问 www.php-cache.com 了解兼容 PSR-6 的缓存池。

日志记录

请求过程中（~之前）发生的错误（例如连接错误，或 4xx/5xx 响应）可以被记录。
主要的日志记录 中间件 是 GuzzleLogMiddleware。
其他 中间件 也可以访问全局新日志回调并实现自己的日志记录。

$client->setNewLog();

重试

如果请求导致一个 预期的 错误（超时，cURL 连接错误等），将会进行重试[默认：2次→可配置]。更多信息请查看 GuzzleRetryMiddleware。

仅限 CCP ESI 的 中间件

每个网络客户端都有自己的 中间件 栈。这些 中间件 仅用于 请求 CCP 的 ESI API。

GuzzleCcpLogMiddleware

对返回带有 warning HTTP 标头（标记为 已弃用 /或 旧版）的端点的请求将被记录到单独的日志文件中。

GuzzleCcpErrorLimitMiddleware

失败的 ESI 请求（4xx/5xx 状态码）实现了“错误率限制”的概念（→ 博客： ESI 错误率限制）。如果在一段时间内请求多次失败，此 中间件 会跟踪记录这些 以及 预先阻止 请求（例如针对用户）的端点，而 CCP 实际上会在之前这么做。

内容编码

“decode-content”的默认配置是 true → 解码“gzip”或“deflate”响应。
大多数 API 只有在请求中找到 Accept-Encoding HTTP 头时才会发送压缩响应数据。一个 string 值会添加此头，并且响应数据会被解码。

$client->setDecodeContent('gzip, deflate');

错误报告

问题可以在这里追踪： https://github.com/exodus4d/pathfinder/issues

开发

如果你是开发者，你可能已经在本地上查看了 两个 存储库（exodus4d/pathfinder，exodus4d/pathfinder_esi）。

在这种情况下，你可能想在你本地的 exodus4d/pathfinder_esi 仓库中测试你的更改，并使用你的本地的 exodus4d/pathfinder 安装。

1. 克隆/检出 两个 仓库到本地相邻的位置
2. 在你的 pathfinder_esi 仓库中进行更改并 提交 修改（不要推送！）
3. 切换到你的 pathfinder 仓库
4. 使用 Composer 和 composer-dev.json 运行，它会从你的 本地 仓库安装 pathfinder_esi。
   • Unix: $set COMPOSER=composer-dev.json && composer update
   • Windows（PowerShell）: $env:COMPOSER="composer-dev.json"; composer update --no-suggest