Seat Laravel Package

Getting Started

SeAT (eveseat/seat) is not a typical drop-in library — it's a full Laravel application for EVE Online corporation/alliance management (ESI tokens, characters, squads, roles, assets, wallets, and a plugin ecosystem). Treat it as a codebase you deploy and extend, not a package you composer require into an existing app.

1. Deploy. Either use the official Docker image (eveseat/seat) or composer create-project eveseat/seat. Requirements in 5.x: PHP 8.x, MySQL/MariaDB, Redis (strongly recommended), and a queue worker.
2. Check your PHP version first. 5.0.2 bumps SeAT's minimum PHP version. Before upgrading, read composer.json (require.php) on the tag you're targeting and confirm your runtime — and your Docker base image — meets it. The official image tracks the requirement; hand-built images and distro PHP packages are where this bites.
3. Configure EVE SSO. Create an application at the EVE developer portal and set EVE_CLIENT_ID, EVE_CLIENT_SECRET, and the callback URL in .env.
4. Boot it. php artisan migrate, then php artisan seat:admin:user to create your first admin.
5. Look here first: config/seat.php and config/eveapi.php (scope groups, ESI tuning), the Seat\Web and Seat\Eveapi namespaces, and app/ for the thin application layer that wires the eveseat/* packages together.
6. First use case: authenticate with EVE SSO, let the character update job pull assets/wallet, create a Squad, and assign that character to it. That single loop — token → ESI job → cached model → squad/role-gated UI — is the shape of nearly everything else in SeAT.

In 5.0.1 the default env settings were committed upstream (PR #902), so a fresh checkout boots with far less hand-editing of .env than 5.0.0. Copy the shipped defaults, then override only what's environment-specific (DB, Redis, SSO credentials, APP_URL).

Implementation Patterns

Working with ESI data. Use the Seat\Eveapi models rather than calling ESI yourself. CharacterInfo::find($id) gives you relations (assets, wallet_balance, skills, corporation, etc.) that are kept fresh by SeAT's scheduled jobs. Tokens live on CharacterInfo->refresh_token; refresh is handled by the eveapi layer, so you rarely touch it manually.

Custom jobs. Model new ESI pulls on existing Seat\Eveapi\Jobs\* classes: extend the base job, declare the scope your endpoint needs, and let the token middleware handle 401/refresh. Register recurring work through the scheduler in your service provider ($schedule->job(...)->hourly()), and make jobs idempotent — they'll retry.

Authorization. SeAT layers three things: roles (global, e.g. Admin/HR), squads (membership-based groups used heavily for corp/alliance gating), and Laravel gates. Prefer Squad-scoped checks in new features — role checks are blunt and admins will expect per-squad targeting.

Plugins. A SeAT plugin is a Composer package with a service provider that registers routes, menu entries, permissions, and migrations. Use the provided menu/ACL extension points and vendor:publish conventions instead of editing core files. This is the supported integration path and survives seat:update.

Pin your plugin's PHP constraint. Since 5.0.2 raises core's minimum PHP, plugins should declare a require.php constraint at least as strict as the core version they target. Otherwise Composer can happily install a plugin on a PHP runtime core rejects — or vice versa — and you get fatal errors at boot rather than at resolve time.

API surface. If you need programmatic access, SeAT ships its own API package with token scopes. Reuse its middleware and scope model rather than inventing a second auth scheme.

Settings. Prefer the global settings helper/store over hardcoding values, so admins can tune behaviour without redeploying.

Gotchas and Tips

• 5.0.2 is a runtime bump, not a code change. "Bumps minimum PHP" means an older PHP will now fail at composer install/boot. Verify PHP version before you git pull on a live instance — otherwise you take the site down during a routine update window. Roll the runtime (or the Docker image tag) first, then the code.
• Config cache hides 5.0.1's new defaults. Laravel's config:cache bakes in values. After upgrading, run php artisan config:clear (or config:cache again) or you'll see the old, sparse configuration and wonder where the defaults went.
• No queue worker, no data. Character updates, token refreshes, and asset pulls are queued. A running queue:work under supervisor (or Horizon) is mandatory in production; the UI silently goes stale without it.
• Migrations on upgrade. Always php artisan migrate after pulling a new SeAT version — core and plugin migrations both need to run. seat:update wraps part of this, but verify.
• ESI scope changes force re-auth. Adding a scope to config/eveapi.php invalidates existing tokens for that scope group; users must re-link. Plan scope changes as a comms event, not a hotfix.
• Rate limits and error budgets. ESI returns 420s with an error budget that degrades under load. SeAT throttles, but large alliances with many characters need queue concurrency tuned down, not up — hammering ESI makes it worse.
• Invalid tokens soft-delete. A 401 typically removes the token rather than throwing loudly; features then quietly lose data for that character. Surface token health in your admin views.
• Permissions on storage/ and bootstrap/cache. The classic Docker bind-mount failure. Match the container's www-data UID or nothing writes.
• Debugging: storage/logs/laravel.log plus failed-job inspection is your primary loop; APP_DEBUG=true is fine locally but should never be on for a public SeAT instance (it exposes SSO secrets in stack traces).
• Don't fork core to customise. Use plugins, service-provider hooks, and settings. Forked core means every SeAT release becomes a merge conflict, and 5.0.x is still moving.
• Version 5.0.1 itself is low-risk — a patch adding default env settings, no breaking changes, no migrations implied. Safe to take from 5.0.0. 5.0.2 carries no schema or API changes either, but its PHP floor is a genuine deployment constraint: treat it as an infrastructure change, and confirm the exact version against composer.json rather than assuming "8.x" still qualifies.