README

最初由 Exodus4D 编写，但由于原始客户端不再维护，已重新创建以支持开源分支。

此 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",
    "goryn-clade/pathfinder_esi": "v2.1.2"
  }
}

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', 'goryn-clade/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();

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

日志记录

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

$client->setNewLog();

重试

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

CCP ESI 独家 中间件

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

GuzzleCcpLogMiddleware

返回包含警告 HTTP头部的已弃用或旧版标记端点的端点请求会被记录到单独的日志文件中。

GuzzleCcpErrorLimitMiddleware

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

内容编码

"decode-content"的默认配置为true → 解码"gzip"或"deflate"响应。
大多数API只有在请求中找到Accept-Encoding HTTP头部时才会发送压缩的响应数据。一个字符串值将添加此头部，并将响应数据解码。

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

错误报告

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

开发

如果您是开发者，您可能已经在本地检查了两个仓库（goryn-clade/pathfinder，goryn-clade/pathfinder_esi）。

在这种情况下，您可能想在您的本地goryn-clade/pathfinder_esi仓库中测试更改，使用您的本地goryn-clade/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