README

Originally written by Exodus4D, but has been recreated to support open-source forks since the oriiginal client is no longer maintained.

This Web API client library is used by Pathfinder and handles all ESI API requests.
Additional APIs can easily be added and can be used side by side with their own configuration. Included clients:

CCP ESI API client: Esi.php
CCP SSO API client: Sso.php
GitHub basic API client: GitHub.php
eve-scout "Thera" API client: EveScout.php

This Web client is build on Guzzle and makes much use of the build in Middleware concept in Guzzle.

Installation:

Use Composer for installation. Packagist does not list v3.0.1, so add this repository as well. Composer then reads the release tags from GitHub. In composer.json add:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/goryn-clade/pathfinder_esi" }
  ],
  "require": {
    "php-64bit": ">=8.2",
    "goryn-clade/pathfinder_esi": "^3.0"
  }
}

Pathfinder: This web API client lib is automatically installed through Composer along with all other required dependencies for the Pathfinder project. (→ see composer.json).

A newer version of Pathfinder may require a newer version of this repository as well. So running composer install after a Pathfinder update will upgrade/install a newer ESI client. Check Pathfinder release notes for further information.

Use Client:

1. Init client:

// 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. Send requests

// get all releases from GitHub for a repo
$releases = $client->send('getProjectReleases', 'goryn-clade/pathfinder');
// … more requests here

Concept

Guzzle Middlewares :

Middlewares classes are small functions that hook into the "request → response" chain in Guzzle.

A Middleware can manipulate the request and response objects
Each Middleware is dedicated to handles its own task.
There are Middlewares for "logging", "caching",… pre-configured.
Each Middleware has its own set of config options that can be set through the $client->.
All configured Middlewares are pushed into a HandlerStack() that gets resolved for each request.
The order in the HandlerStack() is essential!

Guzzle HandlerStack :

This flowchart shows all Middlewares used by ESI.php API client. Each request to ESI API invokes all Middlewares in the following order:

Before request

GuzzleJsonMiddleware → GuzzleLogMiddleware → GuzzleCacheMiddleware → GuzzleCcpLogMiddleware → GuzzleRetryMiddleware → GuzzleCcpErrorLimitMiddleware

After response (→ reverse order!)

GuzzleCcpErrorLimitMiddleware → GuzzleRetryMiddleware → GuzzleCcpLogMiddleware → GuzzleCacheMiddleware → GuzzleLogMiddleware → GuzzleJsonMiddleware

Default Middlewares:

JSON

Requests with expected JSON encoded response data have GuzzleJsonMiddleware in HandlerStack.
This adds Accept: application/json Header to request and response body gets wrapped into JsonStream.

$client->setAcceptType('json');

Caching

A client instance should be set up with a PSR-6 compatible cache pool where persistent data can be stored. Valid response data can be cached by its Cache-Expire HTTP Header. GuzzleCacheMiddleware also handle Etag Headers. Other Middlewares can also access the cache pool for their needs. E.g. GuzzleLogMiddleware can throttle error logging by using the cache pool for error counts,…

→ See: $client->setCachePool();

Hint: Check out www.php-cache.com for PSR-6 compatible cache pools.

Logging

Errors (or other events) during (~before) a request can be logged (e.g. connect errors, or 4xx/5xx responses).
The primary Middleware for logging is GuzzleLogMiddleware
Other Middlewares also have access to the global new log callback and implement their own logs.

$client->setNewLog();

Retry

Requests result in an expected error (timeouts, cURL connect errors,… ) will be retried [default: 2 times → configurable!]. Check out GuzzleRetryMiddleware for more information.

CCP ESI exclusive Middlewares:

Each web client has its own stack of Middlewares. These Middlewares are exclusive for requests to CCP´s ESI API:

GuzzleCcpLogMiddleware

Requests to endpoints that return a warning HTTP Header for deprecated /or legacy marked endpoints get logged into separate log files.

GuzzleCcpErrorLimitMiddleware

Failed ESI requests (4xx/5xx status code) implement the concept of "Error Rate Limiting" (→ blog: ESI error rate limiting). In case a request failed multiple times in a period, this Middleware keeps track of logging this and pre-block requests (e.g. for a user) an endpoint before CCP actual does.

Content Encoding

The default configuration for "decode-content" is true → decode "gzip" or "deflate" responses.
Most APIs will only send compressed response data if Accept-Encoding HTTP Header found in request. A string value will add this Header and response data gets decoded.

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

Bug report

Issues can be tracked here: https://github.com/goryn-clade/pathfinder/issues

Development

To test changes in a local goryn-clade/pathfinder_esi checkout with a local goryn-clade/pathfinder installation, point pathfinder at your checkout with a Composer path repository.

This works for a pathfinder installation that runs from its own folder. It does not work inside a Docker build such as pathfinder-containers: ../pathfinder_esi is outside the build context, and the vendor symlink would point nowhere in the image.

Clone both repositories next to each other, so pathfinder and pathfinder_esi share a parent folder.
In pathfinder_esi, make your changes on a named branch (for example my-change). Composer takes the package version from the branch name, so a detached HEAD does not work.
In pathfinder, add your checkout as a repository. Composer puts it before the GitHub repository, so it wins:
```
composer config repositories.local path ../pathfinder_esi
```
In pathfinder, require your branch as dev-<branch>. After as, put the version of goryn-clade/pathfinder_esi that pathfinder's composer.json requires now, so other constraints still match:
```
composer require "goryn-clade/pathfinder_esi:dev-my-change as <required version>"
```
Composer symlinks vendor/goryn-clade/pathfinder_esi to your checkout. Edits in pathfinder_esi take effect at once; you do not need to commit them.
When you are done, restore pathfinder's composer.json and composer.lock (for example git checkout -- composer.json composer.lock) and run composer install. Do not commit the path repository.

goryn-clade / pathfinder_esi

Package info

Security

Statistics