EVE-Online - ESI API
Web API client forThis 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. In composer.json
require
section add:
{
"require": {
"php-64bit": ">=7.2",
"exodus4d/pathfinder_esi": "v2.0.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', 'exodus4d/pathfinder');
// … more requests here
Concept
Middlewares :
GuzzleMiddlewares classes are small functions that hook into the "request → response" chain in Guzzle.
- A Middleware can manipulate the
request
andresponse
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!
HandlerStack :
GuzzleThis 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/exodus4d/pathfinder/issues
Development
If you are a developer you might have both repositories (exodus4d/pathfinder, exodus4d/pathfinder_esi ) checked out locally.
In this case you probably want to test changes in your local exodus4d/pathfinder_esi repo using your local exodus4d/pathfinder installation.
- Clone/Checkout both repositories local next to each other
- Make your changes in your pathfinder_esi repo and commit changes (no push!)
- Switch to your pathfinder repo
- Run Composer with
composer-dev.json
, which installs pathfinder_esi from your local repository.- Unix:
$set COMPOSER=composer-dev.json && composer update
- Windows (PowerShell):
$env:COMPOSER="composer-dev.json"; composer update --no-suggest
- Unix: