Download the PHP package seatplus/esi-schema without Composer

seatplus/esi-schema

A fully typed PHP SDK for EVE Online's ESI API, generated from the official OpenAPI spec. Every one of the ~218 endpoints gets its own class, with its required OAuth scope, cache lifetime, rate-limit group and response shape available as typed constants and DTOs — so your IDE and PHPStan know them, instead of you looking them up.

Zero runtime dependencies. PHP 8.5+.

What problem does this solve?

ESI is EVE Online's official REST API. Calling it from PHP normally means untyped arrays and a lot of tribal knowledge that lives in documentation rather than in your code:

With this package, all of that is code:

That means a mistyped field name is a static-analysis error rather than a runtime null, and a missing OAuth scope is something you can check before dispatching a job instead of discovering from a 403.

What you get

• ~218 endpoint classes — one per ESI route, grouped into 36 tag namespaces.
• 268 response DTOs — typed, readonly value objects for every response schema.
• Pre-call metadata as typed constants — scope, cache age, rate-limit group and window, required in-game roles, cursor pagination.
• Two call styles — static calls for jobs and services, or a fluent {Tag}Resource API when you already hold a transport.
• Zero runtime dependencies — no HTTP client, no framework, no YAML parsing at runtime. Everything is baked into generated PHP at build time.
• Honest versioning — the version tracks this package's PHP API, and the ESI compatibility date is readable at runtime. See Versioning.

What this is not

It does not make HTTP requests. There is no OAuth, no caching, no retry logic and no Guzzle in here — deliberately. Every endpoint takes an EsiTransportInterface, which is a single method you implement (or get from seatplus/esi-client). That keeps this package free of version conflicts and makes the whole test suite network-free.

See Implementing a Transport if you want to wire it to your own HTTP client.

Who it's for

• You call ESI from PHP and want the compiler and your IDE to help.
• You run background jobs and need scope, cache and rate-limit facts before dispatching.
• You want ESI's breaking changes to show up as a reviewable diff and a semver bump rather than a surprise in production.

Installation

Requirements: PHP 8.5+

Most applications will also want a transport implementation:

Related packages

Quick Start

Two call styles are available. Choose based on context.

Option A — Direct static call (recommended for jobs and services)

Each ESI endpoint has its own generated class under src/Resources/{Tag}/:

Option B — Fluent API (convenient for interactive use and esi-client)

A generated {Tag}Resource wrapper class exists for every tag. Inject the transport once and call methods fluently:

Each {Tag}Resource method is a thin wrapper — it simply calls {OperationClass}::execute($this->transport, ...). Pre-call metadata and typed constants remain on the per-route class.

Namespace table

Resource classes are grouped by ESI tag into 36 subfolders, each with a corresponding tag-group wrapper:

Per-route classes: Seatplus\EsiSchema\Resources\{Tag}\{PascalCaseOperationId}
Tag wrappers: Seatplus\EsiSchema\Resources\{Tag}Resource (e.g. Seatplus\EsiSchema\Resources\AssetsResource)

eveapi integration pattern

The intended use in queue jobs:

Implementing a Transport

All resource classes depend only on EsiTransportInterface. Implement it to connect any HTTP client:

$method always arrives as an uppercase HTTP method token — GET, POST, PUT, DELETE — as RFC 9110 §9.1 requires. Method tokens are case-sensitive, so forward it verbatim; there is no need to normalise it.

The reference implementation is seatplus/esi-client, which handles OAuth, RFC 7234 caching, error-limit tracking, and retry logic.

Architecture

Key contracts:

Design Decisions

1. Static resource classes — one class per ESI endpoint

Each ESI endpoint is represented as a pure static class (final class) rather than an instance method on a tag-grouped resource. This means:

• Zero allocation: GetCharactersCharacterIdAssets::meta() is a direct static call — no new, no DI.
• PHPStan traces the return type directly: ::execute() returns EsiResult<GetCharactersCharacterIdAssetsItem>, fully known at static analysis time.
• The class name is the identifier: OPERATION = GetCharactersCharacterIdAssets::class is a typed constant reference — no magic strings needed in jobs.

2. Typed public constants for metadata

Each generated class exposes 7 individually typed public const declarations:

meta() simply wraps these into new OperationMeta(...). The constants are also directly accessible without any method call or allocation.

3. OperationMeta as a pure typed DTO

OperationMeta is a final readonly class with only typed constructor properties — no methods. Access its values as $meta->requiredScope, $meta->cacheAge, etc.

Token validation logic is not in this library — tokenSatisfies() was removed. Scope checks belong in eveapi, where the token models live.

4. Tag-based subfolders

The 218 resource classes live in src/Resources/{Tag}/ (36 subfolders), matching ESI's tag taxonomy:

• Group imports are idiomatic: use Seatplus\EsiSchema\Resources\Assets\{GetCharactersCharacterIdAssets, GetCorporationsCorporationIdAssets}.
• Tag names with spaces become PascalCase: Faction Warfare → FactionWarfare.

5. Zero runtime dependencies

composer.json has no require entries (only require-dev for symfony/yaml used by the generator). The published library is pure PHP 8.5.

6. EsiTransportInterface as the sole injection boundary

All network I/O is delegated to a single invoke() method. The library knows nothing about Guzzle, cURL, OAuth tokens, or HTTP caching. Tests mock this interface — no network required.

7. The version is semver over the PHP surface; the ESI date is metadata

The library version describes this package's PHP API, not ESI's calendar. A new compatibility date is data carried by a release, not a component of the version number. See Versioning.

Versioning

seatplus/esi-schema follows plain semver over its generated PHP surface:

A new compatibility date is therefore at least a minor — it changes the X-Compatibility-Date a transport sends, which is real behaviour — but is never automatically a major.

How to pin

Pinning an exact version is the only honest way to pin a date: a caret constraint spans an open-ended range of future releases, so ^4.0 cannot express "the 2026-07-21 wire contract".

There are no N.x branches. Packagist serves every constraint from tags, and generated code is committed, so every compatibility date this package ever shipped remains installable at its own tag forever.

Which date am I on?

A transport must send COMPATIBILITY_DATE_HEADER: COMPATIBILITY_DATE on every request. Reading it from here rather than hard-coding a literal is what keeps the generated types and the server's response shape from disagreeing — a composer update then moves both together.

How releases happen

.github/workflows/esi-sync.yml runs daily. It regenerates against the newest published compatibility date and compares the resulting API surface manifest (.esi/surface.json) with the one in the newest semver tag:

• nothing changed → nothing happens;
• patch or minor → it opens a pull request with auto-merge enabled. CI runs, the required check passes, the PR merges itself, and release.yml tags it. No human involved.
• major → it opens a pull request without auto-merge and reports it on one reused issue. The regeneration, the classifier's report and the full Verify run are already done; what is left is the decision. To release it, add the release:major label and merge — release.yml reads that label off the merged pull request and tags. Merge without the label and the code lands while nothing is tagged, which is the safe default; release.yml can still be dispatched with bump=major afterwards.
• unclassifiable → no pull request, nothing released, one issue for a human.

release.yml watches main, so a bot-merged sync and a human-merged PR take the identical path to a tag. It never tags a major that no human authorised, refuses to re-tag an existing version, and afterwards checks the release is actually resolvable on Packagist.

The release:major label also raises a computed patch or minor to a major, for breakage the surface diff cannot see — a behavioural change, a corrected contract. It cannot lower a bump; that still needs a dispatch with a stated reason.

Nothing in this pipeline bypasses branch protection — the bot goes through the same required check as anyone else.

Majors are held back deliberately. Composer never force-upgrades a ^3.0 consumer to 4.0.0, but it also cannot protect anyone from a bug in the classifier publishing a removal as a minor — and a Packagist tag cannot be withdrawn.

Regenerating

Omit --compatibility-date for a local run and the newest published date is used. It is required under --strict (implied in CI) so that an unattended run can never guess which spec to build from.

The generator reads https://esi.evetech.net/meta/openapi.yaml?compatibility_date=<date> and vendors the exact bytes it consumed to .esi/openapi.yaml, so the tree can be reproduced offline:

It emits (current counts are asserted by tests/Unit/GeneratedSpecTest.php and recorded in GeneratedSpec):

• src/Responses/*.php — 268 typed DTO classes, one per ESI schema object
• src/Resources/{Tag}/*.php — 218 per-route static classes in 36 tag subfolders
• src/Resources/{Tag}Resource.php — 36 tag-group wrappers for the fluent API
• src/GeneratedSpec.php — provenance constants
• .esi/surface.json — the public API manifest that drives release classification
• .esi/state.json — compatibility date, spec hash, manifest hash, counts

Generation prunes: anything under src/Responses or src/Resources that the spec no longer describes is deleted. Without that, removed endpoints linger and no diff can ever see a removal.

Do not manually edit generated files. Changes are overwritten on next regeneration. To change generated output, edit bin/generate.php.

Testing

Contributing

See ARCHITECTURE.md for detailed design rationale.