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 客户端库将通过 Composer 自动安装，包括 Pathfinder 项目所需的所有其他依赖项。（→ 查看 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。
这会给 请求 添加 Accept: application/json 头部，并且 响应 体的内容会被包装成 JsonStream。

$client->setAcceptType('json');

缓存

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

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

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

日志记录

请求过程中（~之前）发生的错误（例如连接错误，或 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 安装来测试您在 本地 exodus4d/pathfinder_esi 仓库中的更改。

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