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 中的内置 Middleware 概念。

安装

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

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

Pathfinder: 此 Web API 客户端库将通过 Composer 自动安装，包括 Pathfinder 项目所需的所有其他依赖项。（→ see 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 编码的 response 数据的请求在 HandlerStack 中包含 GuzzleJsonMiddleware。
这会在 request 中添加 Accept: application/json Header，并将 response 的 body 包装成 JsonStream。

$client->setAcceptType('json');

缓存

客户端实例 应该 配置为与 PSR-6 兼容的缓存池，其中可以存储 持久 数据。有效的 response 数据可以通过其 Cache-Expire HTTP Header 进行缓存。 GuzzleCacheMiddleware 还处理 Etag Headers。其他 中间件 也可以根据需要访问缓存池。例如，GuzzleLogMiddleware 可以通过使用缓存池来跟踪错误计数等来 节流 错误日志。

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

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

日志记录

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

$client->setNewLog();

重试

请求导致 预期 的错误（超时、cURL 连接错误等）将被重试（默认：2 次 → 可配置！）。有关更多信息，请查看 GuzzleRetryMiddleware。

CCP ESI 独家 中间件

每个网络客户端都有自己的 中间件 栈。这些 中间件 是为对 CCP 的 ESI API 的 requests 专属的。

GuzzleCcpLogMiddleware

返回标记为 已弃用 或 旧版 的端点的 warning HTTP Header 的请求将被记录到单独的日志文件中。

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-dev.json 运行 Composer，它从您的 本地 仓库安装 pathfinder_esi。
   • Unix: $set COMPOSER=composer-dev.json && composer update
   • Windows (PowerShell): $env:COMPOSER="composer-dev.json"; composer update --no-suggest