Download the PHP package seatplus/esi-client without Composer

Esi-Client

A standalone ESI (Eve Swagger Interface) Client Library using kevinrob/guzzle-cache-middleware.

Requires PHP 8.5.

ESI compatibility date: not configured here. It is read from seatplus/esi-schema's GeneratedSpec::COMPATIBILITY_DATE and sent as X-Compatibility-Date on every request, so the generated response DTOs and the shape the server returns cannot disagree. Override it with new EsiConfiguration(compatibilityDate: '…'), or pass null to omit the header and let ESI apply its own default. ESI validates the header and answers 400 for a malformed or out-of-range date, so a typo fails every request.

esi-schema tags a new major for each breaking ESI spec sync, and this branch accepts that range (^4.1 || ^5.0), so composer update can move the compatibility date without an esi-client release. To see the date you are actually sending:

Pin esi-schema in your own composer.json if you need it frozen.

4.x declares php: ^8.3, but its require-dev pins pestphp/pest ^5.0, which needs php ^8.4 — composer install of 4.x fails on 8.3 and CI never tests below 8.5. Consumers are unaffected, since dev dependencies are not installed for them, but that 8.3 floor is unverified.

Installation

You can install the package via composer:

Usage

Typed SDK (recommended)

The SDK exposes typed resource methods. Single-object endpoints return the DTO directly (a subclass of AbstractEsiDto); paginated list endpoints return EsiResult<array<T>>.

Low-level transport

Caching

There is no response cache by default. EsiConfiguration::$cacheMiddleware defaults to NullCacheMiddleware, which stores nothing; you opt in by setting it to LaravelFileCacheMiddleware (or your own CacheMiddlewareInterface implementation).

When you do opt in, responses are cached per RFC 7234 and the key is scoped to both the caller and the compatibility date — sha256(compatibility-date | token subject | method + URI), via Seatplus\EsiClient\CacheMiddleware\Strategy\EsiPrivateCacheStrategy. The token scoping matters: ESI does not send Vary: Authorization, so an unscoped key lets two characters requesting the same authenticated URI share one entry, and a character lacking a corporation role can be served a payload another character fetched without ESI ever seeing the request it would have refused. The subject comes from the access token's JWT sub claim, which is stable across token refresh; a token that is not a readable JWT falls back to hashing the header, which isolates it but only caches for that token's lifetime. Note the claim is read without signature verification — that only helps against a caller who cannot already supply an arbitrary token.

A compatibility-date change means a one-time cold cache for the affected entries. Old entries are not deleted; on the file store, responses carrying an ETag were saved with an infinite TTL, so run php artisan cache:clear if you want the space back.

If you implement CacheMiddlewareInterface yourself, build on EsiPrivateCacheStrategy rather than Kevinrob\GuzzleCache\Strategy\PrivateCacheStrategy — otherwise your cache keeps the unscoped key and the cross-character bleed above.

Rate limiting

ESI enforces a 1800-token / 15-minute rolling window (one token consumed per request, irrespective of response code). esi-client itself does not throttle — rate limiting is handled by the consumer layer (eveapi) using Laravel Horizon throttle middleware on each queued job.

If the HTTP client receives a 420 Error Limited response, the request is retried with exponential backoff as configured on the job.

Error handling

Guzzle is an implementation detail: no GuzzleHttp\Exception\* type escapes this package. Everything it throws lives in Seatplus\EsiClient\Exceptions and implements the EsiClientException marker interface, so catch (EsiClientException $e) catches any failure originating here.

One exception is deliberately not covered: assertScope() throws Seatplus\EsiSchema\Contracts\ScopeAccessDeniedException, which belongs to esi-schema. Catch it separately if you need it.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

As of today this esi client only supports Laravel Cache Middleware. However Kevinrob/guzzle-cache-middleware supports various others such as:

• Doctrine cache
• Laravel cache
• Flysystem
• PSR6
• WordPress Object Cache

if you plan to use this client with any of these a proper CacheMiddleware would be needed. Build its strategy on Seatplus\EsiClient\CacheMiddleware\Strategy\EsiPrivateCacheStrategy so the cache key stays scoped to the caller and the compatibility date — see Caching. Same goes to the HTTP client. This client and its cache middleware had been designed to use with Guzzle7 (but you can use it with any PSR-7 HTTP client). Please submit your PR accordingly implementing other HTTP clients.

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Felix Huber
• All Contributors

License

The MIT License (MIT). Please see License File for more information.