Eveapi Laravel Package

Getting Started

eveseat/eveapi is the ESI (EVE Swagger Interface) integration layer used by SeAT and standalone Laravel apps. It wraps EVE Online's OAuth2 SSO and the ESI REST API into Laravel-native services, facades, and Eloquent-style models.

Install and publish:

composer require eveseat/eveapi
php artisan vendor:publish --provider="Seat\Eveapi\EveapiServiceProvider"
php artisan migrate

Add your EVE application credentials to .env (register the app at https://developers.eveonline.com/):

EVE_CLIENT_ID=
EVE_CLIENT_SECRET=
EVE_CALLBACK_URL="${APP_URL}/eveapi/auth/callback"
EVE_SCOPES="esi-characters.read_contacts.v1 esi-assets.read_assets.v1"

Where to look first:

• config/eveapi.php — scopes, ESI base URI, user-agent, cache TTLs.
• src/Jobs/ — the queue jobs that refresh tokens, assets, contacts, etc.
• src/Services/ — the service wrappers around each ESI endpoint.
• src/Models/ — the Character, Corporation, Alliance, Token Eloquent models.

First use case: authenticate a user via EVE SSO, persist the character + refresh token, then dispatch a job to pull their assets. The Token model is the anchor for every authenticated ESI call.

Implementation Patterns

SSO login flow. Redirect users to the SSO URL, handle the callback, then run Character::updateOrCreate and store the token. The package handles the token exchange for you; you own the redirect.

Token refresh as a job. Tokens expire (~20 min). Do not refresh inline in request handlers. Instead, use the package's scheduler pattern:

// In a scheduled command or job
Token::where('expires_at', '<', now()->addMinutes(15))
    ->each(fn ($token) => RefreshToken::dispatch($token));

Chain dependent jobs on the refreshed token so ESI calls don't 401 mid-flight.

Service calls. Each ESI endpoint has a service class. Prefer injecting the service over calling the facade:

public function __construct(private AssetService $assets) {}

public function handle(): void
{
    $assets = $this->assets->setToken($this->token)->all();
}

Rate limiting. ESI enforces error limits per endpoint. Route bulk fetch jobs through the queue with ->onQueue('esi') and back off using RateLimitExceeded exceptions. Wrap calls in a retry with a longer backoff — 60s+ on 429s.

Eager-loading relations. Fetch a character with ->with('corporation', 'alliance') before rendering lists; the raw ESI payload doesn't hydrate those.

Integration. Use Character::find($id)->refreshAssets() style methods if available, otherwise dispatch the package's own jobs. Do not build parallel ESI clients — the package's user-agent and error handling are tuned for ESI's behavior.

Gotchas and Tips

Version resolution (5.0.37). This release fixes an edge case where the package version was not assigned when the environment variable was unset — meaning EVEAPI_VERSION (or whatever the internal key is) could resolve to null in deployments that rely on composer.lock rather than explicit env config. If you pin the package version at runtime for user-agent headers or reporting, set the env var explicitly or ensure you are on 5.0.37+. Without the fix, a missing env var produced a broken or empty version string, which ESI may reject or rate-limit differently.

Scopes must match. If you change EVE_SCOPES, existing tokens keep their original scopes. Users must re-authenticate. Do not assume a config change takes effect for existing users.

Refresh token rotation. EVE occasionally rotates refresh tokens. If you store tokens in your own table instead of the package's, you will lose the rotation and get 401s. Let the package own the Token row.

Cache collisions. The package caches ESI responses keyed by token and endpoint. If you flush application cache, ESI data disappears too — expect a thundering herd on next request. Stagger refreshes.

Queue workers. Long-running workers hold tokens in memory. Restart workers after deploys; stale tokens cause silent 401 loops on the next scheduled run.

Error 420 (error limit). ESI returns 420, not 429, when you exceed the error limit. Handle both. Back off for at least 60 seconds and inspect X-ESI-Error-Limit-Remain.

Debugging. Enable Laravel's HTTP client logging for esi.evetech.net in config/logging.php. The package's exceptions carry the ESI response body — dump it before wrapping in generic Exception.

Extension points. The package is deliberately thin over HTTP. If you need a new endpoint, the cleanest path is a subclass of an existing service or a custom job that reuses RefreshToken. Avoid forking; the SSO and token lifecycle are the fragile parts.

Laravel version compatibility. Check composer.json constraints against your Laravel version before upgrading majors. Patch releases like 5.0.37 are safe to adopt but bumping majors has historically required config re-publish.