Skip to content

feat: integrate seatplus/esi-schema — DTOs from esi-schema, direct DTO returns #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
herpaderpaldent merged 1 commit into from
May 11, 2026
Merged

feat: integrate seatplus/esi-schema — DTOs from esi-schema, direct DTO returns #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 33 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,10 @@

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

> **ESI compatibility date:** This branch of `esi-client` targets ESI compatibility date **`2025-12-16`** and forward.
> Responses DTOs are sourced from [`seatplus/esi-schema`](https://github.com/seatplus/esi-schema) (`1.x`).
> If CCP publishes a new breaking compatibility date, a new major version of both packages will be released.

## Installation

You can install the package via composer:
Expand All @@ -21,10 +25,37 @@ composer require seatplus/esi-client

## 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>>`.

```php
$esi = new Seatplus\EsiClient\EsiClient();
use Seatplus\EsiClient\EsiClient;

$sdk = new EsiClient();

// Single object — returns AllianceDetail directly
$alliance = $sdk->alliance()->getAlliancesAllianceId(99000006);
echo $alliance->name; // typed readonly string
echo $alliance->ticker;
$alliance->isCachedLoad; // bool — true if served from RFC 7234 cache

// Authenticated endpoint — returns CharactersDetail directly
$character = $sdk->withToken($accessToken)->characters()->getCharactersCharacterId(95725047);
echo $character->name;

// Paginated list — returns EsiResult (pages metadata needed)
$result = $sdk->withToken($accessToken)->assets()->getCharactersCharacterIdAssets(95725047, page: 1);
echo $result->pages; // total pages from X-Pages header
foreach ($result->data as $asset) {
echo $asset->item_id; // typed readonly int
}
```

### Low-level transport

$esi->setVersion('v5'); // if you do not set a version, esi-client is using '/latest'
```php
$esi = new EsiClient();

// make a call — returns EsiResponse
$response = $esi->invoke('get', '/characters/{character_id}/', [
Expand All @@ -36,23 +67,6 @@ $response = $esi->invoke('get', '/characters/{character_id}/', [
// $response->isCachedLoad() — true if served from RFC 7234 cache
```

### Response shapes are the consumer's responsibility

`esi-client` is a **pure transport layer**. It decodes the JSON body into a `stdClass` and
returns it as `$response->data`. It has no knowledge of what fields each ESI endpoint returns.

In `eveapi`, every job wraps `$response->data` in a typed `readonly class` DTO via a
`from(object $data): self` factory before touching any properties:

```php
// eveapi example — consuming an EsiResponse with a typed DTO
$data = CharacterInfoResponse::from($response->data);
CharacterInfo::updateOrCreate(
['character_id' => $this->character_id],
['name' => $data->name, 'corporation_id' => $data->corporation_id],
);
```

### Rate limiting

ESI enforces a **1800-token / 15-minute** rolling window (one token consumed per request,
Expand Down
Loading
Loading