exodus4d/pathfinder_esi

Pathfinder 的 ESI API 库

维护者

详细信息

github.com/exodus4d/pathfinder_esi

主页

源代码

安装数: 3,655

依赖关系: 0

建议者: 0

安全性: 0

星标: 3

关注者: 3

分支: 15

v2.0.1 2020-03-22 14:23 UTC

Requires

MIT 3fbd58eaa86c472f91b8c3a0fdb029d9fd903525

  • Mark Friedrich <pathfinder.woop@exodus4d.de>

This package is auto-updated.

Last update: 2024-09-23 00:21:17 UTC

README

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

这个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 编码 响应 数据的请求在 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 的 中间件

每个网络客户端都有自己的 中间件 堆栈。这些 中间件 专用于对 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-dev.json运行Composer，该文件将从你的本地存储库安装pathfinder_esi。
    • Unix：$set COMPOSER=composer-dev.json && composer update
    • Windows（PowerShell）：$env:COMPOSER="composer-dev.json"; composer update --no-suggest