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 项目的所有其他必需依赖项。（→参见 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() 为每个请求进行 解析。
• 在 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 头部，并且 response 的 body 被包装进 JsonStream。

$client->setAcceptType('json');

缓存

应该使用一个与 PSR-6 兼容的缓存池来配置客户端实例，其中可以存储 持久 数据。有效的 response 数据可以通过其 Cache-Expire HTTP 头部进行缓存。GuzzleCacheMiddleware 也处理 Etag 头部。其他 中间件 也可以根据需要访问缓存池。例如，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 头部表示 deprecated 或 legacy 标记端点的端点请求，将被记录到单独的日志文件中。

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 仓库中的更改。

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