Eveapi Laravel Package

Getting Started

Install the package and let it wire itself into the container:

composer require seatplus/eveapi
php artisan vendor:publish --tag=eveapi-config   # config/eveapi.php
php artisan vendor:publish --tag=eveapi-migrations
php artisan migrate

Then set the ESI application credentials in .env (EVE_CLIENT_ID, EVE_CLIENT_SECRET, EVE_CALLBACK_URL — confirm exact keys in the published config/eveapi.php; the service provider reads them at boot, so php artisan config:cache afterwards).

Where to look first:

1. config/eveapi.php — client credentials, scopes, model/table overrides, cache and queue settings.
2. src/Models/ — CharacterInfo and friends (Corporation, Alliance, token models). This is the layer you will query in your app.
3. src/ service bindings + routes — check php artisan route:list | grep -i eve to see whether the package registered its SSO callback for you or expects you to define one.
4. src/Jobs / console commands — the shipped token-refresh and sync jobs you can schedule rather than reinvent.

First use case: add a character via EVE SSO, persist the refresh token, then read $character->corporation / $character->alliance in a controller. Do that end-to-end before writing any sync logic — it validates credentials, scopes, callback URL and migrations in one pass.

Implementation Patterns

Token lifecycle is the core abstraction. Almost everything else is downstream of having a valid access token per character. Drive it through the package's refresh token model/service rather than storing raw tokens yourself; treat a 400 invalid_grant from the token endpoint as "this character needs re-authentication" and mark the record accordingly instead of retrying.

Wrap ESI access in your own service/job layer. Don't call endpoints from controllers. A thin EsiService/FetchCharacterAssets job that depends on the package client keeps you insulated from endpoint changes and gives you one place to add logging, retries and rate limiting.

Fan out per character, queue it, and constrain it.

SyncCharacterAssets::dispatch($character)
    ->onQueue('esi')
    ->middleware([WithoutOverlapping::class]);

Use WithoutOverlapping keyed on character_id, plus a Redis-backed throttle, so a hundred-character corp doesn't trip ESI's error budget.

Respect caching headers. ESI GET responses carry Expires; cache the parsed result with that TTL (Cache::remember($key, $ttl, ...)) rather than a hardcoded 60s. ETag/If-None-Match support is worth wiring if you poll the same endpoints often.

Pagination: iterate ?page=N until an empty array is returned. Not every endpoint returns X-Pages, so don't gate your loop on that header alone.

Extending models (relevant to 5.1.1): if you subclass a package model, declare the parent explicitly so static analysis and consuming packages resolve it:

/** @extends \Seatplus\Eveapi\Models\Character\CharacterInfo */
class Character extends CharacterInfo {}

Then either point the package's model config at your subclass or keep a separate Eloquent model with a belongsTo back to the package model — pick one and stick to it, because the package's relations will still return its own classes.

Testing: fake at the HTTP layer (Http::fake([...])) rather than mocking the package client, so your code exercises the real parsing/normalisation. Use RefreshDatabase and remember the package migrations ship fixtures you probably don't want in tests — verify what gets seeded.

Events as an integration seam: hook the package's character-added / token-refreshed events to trigger your own downstream syncs instead of polling for new rows.

Gotchas and Tips

• ESI error limit is brutal. ~100 errors in a rolling minute gets your application banned briefly and every caller starts failing. Catch the package's error-limit exception explicitly and back off; never put a bare retry(3) around ESI calls.
• Scopes are fixed at SSO time. Adding a scope to config does nothing for existing tokens. Store the granted scopes, compare them to what your code needs, and surface a "re-authenticate" state in the UI.
• Refresh tokens get revoked (password change, ESI revocation, inactivity). Handle it as a normal state, not an exception — a nullable/invalid marker plus an event beats a 500 in a scheduled job.
• Migration collisions. If you're running this inside SeAT or alongside another EVE package, check table names and prefixes in the published migrations before running migrate in production. Publish, diff, then migrate.
• 5.1.1 / type declarations: this patch makes model type declarations resolvable by consuming packages. If you had added @phpstan-ignore, @mixin, or hand-written stubs to work around unresolved model types when extending package models, remove them, upgrade, and re-run Larastan/PHPStan plus barryvdh/laravel-ide-helper:models. No breaking changes are expected from 5.1.0 — it's a patch, so composer update seatplus/eveapi and clear caches is the whole migration.
• Config caching surprises. Credentials and scope lists are read through config; changing .env without config:clear is the #1 cause of "it works in tinker but not in the app".
• Dates come back UTC, cast to Carbon by the models. Don't re-apply timezone conversion twice when displaying.
• Bulk syncs should be resumable. Store a cursor/last-synced timestamp per character per dataset (assets, wallet, contracts) so a killed worker doesn't restart from page one and burn the error budget.
• Debugging: log the outgoing request/response pair (URL, status, remaining error count) at debug level, and log the parsed ESI error body — ESI's human-readable message is far more useful than the HTTP status.