PHPackages                             chronoarc/comicvine - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. chronoarc/comicvine

ActiveLibrary[API Development](/categories/api)

chronoarc/comicvine
===================

A PHP wrapper for the Comicvine API

1.0.0(1mo ago)112MITPHPPHP >=8.2CI passing

Since Nov 15Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/fakeheal/comicvine-sdk)[ Packagist](https://packagist.org/packages/chronoarc/comicvine)[ RSS](/packages/chronoarc-comicvine/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (2)Dependencies (8)Versions (3)Used By (0)

🦸 Comicvine PHP SDK
===================

[](#-comicvine-php-sdk)

[![Tests](https://github.com/fakeheal/comicvine-sdk/actions/workflows/php.yml/badge.svg)](https://github.com/fakeheal/comicvine-sdk/actions/workflows/php.yml)[![Packagist Version](https://camo.githubusercontent.com/7bc6f5fb9366342609abe71e76035fb54927057fabd3876825061301dc08309d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368726f6e6f6172632f636f6d696376696e65)](https://camo.githubusercontent.com/7bc6f5fb9366342609abe71e76035fb54927057fabd3876825061301dc08309d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368726f6e6f6172632f636f6d696376696e65)[![Packagist Downloads](https://camo.githubusercontent.com/d6b400b3de663f482347e73f05faec94befc084a27606b4c0c54b2f2484870a9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368726f6e6f6172632f636f6d696376696e65)](https://camo.githubusercontent.com/d6b400b3de663f482347e73f05faec94befc084a27606b4c0c54b2f2484870a9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368726f6e6f6172632f636f6d696376696e65)

A lightweight, slightly opinionated PHP SDK for the [ComicVine API](https://comicvine.gamespot.com/api/), built on top of [Saloon v4](https://docs.saloon.dev). Every documented ComicVine endpoint is covered, with typed DTOs for every response.

📦 Installation
--------------

[](#-installation)

```
composer require chronoarc/comicvine
```

Requires PHP 8.2+. Grab an API key at [comicvine.gamespot.com/api](https://comicvine.gamespot.com/api/).

🚀 Quick start
-------------

[](#-quick-start)

```
use Chronoarc\Comicvine\Comicvine;

$comicvine = new Comicvine('your-api-key');

// Fetch a single resource — /issue/4000-6
$issue = $comicvine->issues()->get(6)->dto();
echo $issue->name;              // "The Lost Race"
echo $issue->volume->name;      // "Chamber of Chills Magazine"
echo $issue->image->originalUrl;

// List resources — /volumes
$volumes = $comicvine->volumes()->all(limit: 50)->dto();
echo $volumes->numberOfTotalResults;
foreach ($volumes->results as $volume) {
    echo $volume->name;
}

// Search everything — /search
$results = $comicvine->search()->query('Batman', resources: ['character'])->dto();
```

Every resource method returns a Saloon `Response`; you choose how to consume it:

```
$response = $comicvine->characters()->get(1699);

$response->dto();     // typed DTO (Character)
$response->json();    // raw decoded payload
$response->status();  // HTTP status code
```

🗂 Resources
-----------

[](#-resources)

Every ComicVine resource is exposed through a method on the `Comicvine` connector:

Connector methodEndpointsDTOs`$comicvine->characters()``/characters`, `/character``Character`, `CharactersList``$comicvine->chats()``/chats`, `/chat``Chat`, `ChatsList``$comicvine->concepts()``/concepts`, `/concept``Concept`, `ConceptsList``$comicvine->episodes()``/episodes`, `/episode``Episode`, `EpisodesList``$comicvine->issues()``/issues`, `/issue``Issue`, `IssuesList``$comicvine->locations()``/locations`, `/location``Location`, `LocationsList``$comicvine->movies()``/movies`, `/movie``Movie`, `MoviesList``$comicvine->objects()``/objects`, `/object``ComicObject`, `ObjectsList``$comicvine->origins()``/origins`, `/origin``Origin`, `OriginsList``$comicvine->people()``/people`, `/person``Person`, `PeopleList``$comicvine->powers()``/powers`, `/power``Power`, `PowersList``$comicvine->promos()``/promos`, `/promo``Promo`, `PromosList``$comicvine->publishers()``/publishers`, `/publisher``Publisher`, `PublishersList``$comicvine->search()``/search``SearchResults``$comicvine->series()``/series_list`, `/series``Series`, `SeriesList``$comicvine->storyArcs()``/story_arcs`, `/story_arc``StoryArc`, `StoryArcsList``$comicvine->teams()``/teams`, `/team``Team`, `TeamsList``$comicvine->videoCategories()``/video_categories`, `/video_category``VideoCategory`, `VideoCategoriesList``$comicvine->videos()``/videos`, `/video``Video`, `VideosList``$comicvine->videoTypes()``/video_types`, `/video_type``VideoType`, `VideoTypesList``$comicvine->volumes()``/volumes`, `/volume``Volume`, `VolumesList``$comicvine->meta()``/types``Type`, `TypesList`All list endpoints share the same signature:

```
$comicvine->issues()->all(
    limit: 100,                          // page size, API max is 100
    offset: 200,                         // zero-based offset for pagination
    fieldList: ['id', 'name', 'volume'], // trim the response to specific fields
    sort: 'cover_date:desc',             // field:asc or field:desc
    filter: ['volume' => 1487],          // field => value pairs
);
```

All detail endpoints share the same signature:

```
$comicvine->characters()->get(1699, fieldList: ['id', 'name', 'publisher']);
```

### Pagination

[](#pagination)

List DTOs extend `PaginatedList` and expose the full envelope:

```
$page = $comicvine->issues()->all(limit: 100)->dto();

$page->numberOfTotalResults; // e.g. 1024872
$page->numberOfPageResults;  // e.g. 100
$page->limit;                // 100
$page->offset;               // 0
$page->hasMorePages();       // true

$next = $comicvine->issues()->all(limit: 100, offset: $page->offset + $page->limit)->dto();
```

### Search

[](#search)

`/search` paginates with a 1-based `page` parameter and caps `limit` at 10. Results are mixed-type: each item is hydrated into the DTO matching its `resource_type` (unknown types are kept as raw arrays):

```
use Chronoarc\Comicvine\Dto\Character\Character;

$results = $comicvine->search()->query('Batman', resources: ['character', 'volume'], page: 1)->dto();

foreach ($results->results as $result) {
    if ($result instanceof Character) {
        echo $result->realName; // "Bruce Wayne"
    }
}
```

🧬 DTOs
------

[](#-dtos)

- Every DTO is `readonly` and hydrated via `::fromArray()`; you never parse JSON yourself.
- Fields the API omits — association fields on list responses, or anything excluded via `field_list` — are `null`, never missing. `null` means "not fetched", an empty array means "fetched, and empty".
- Cross-resource pointers are `Reference` objects (`id`, `name`, `apiDetailUrl`, `siteDetailUrl`). Specialised references add context: `IssueReference` (`issueNumber`), `EpisodeReference` (`episodeNumber`), `PersonCredit`(`role`), `CountedReference` (`count`, used by volume credits).
- `image` fields hydrate into `Image` with all size renditions (`iconUrl` … `originalUrl`).
- Gender is the `Chronoarc\Comicvine\Enum\Gender` enum (`Other` / `Male` / `Female`).
- Quirks are normalised: the story arc `count_of_isssue_appearances` typo (sic, ComicVine's spelling) maps to `countOfIssueAppearances`, and a person's `death` object is flattened to a date string.

⚠️ Error handling
-----------------

[](#️-error-handling)

The connector uses Saloon's `AlwaysThrowOnErrors`, so any non-2xx response throws a Saloon request exception:

```
use Saloon\Exceptions\Request\RequestException;

try {
    $comicvine->issues()->get(999999999)->dto();
} catch (RequestException $e) {
    $e->getResponse()->status();
}
```

ComicVine rate-limits API keys to 200 requests per resource per hour. Be a good citizen: request only the fields you need via `fieldList`, and cache responses where you can.

🧩 Extending
-----------

[](#-extending)

The SDK is deliberately thin so you can reach into any layer:

- **Custom requests** — extend `Chronoarc\Comicvine\Requests\ListRequest` or `DetailRequest` and send them with `$comicvine->send(new MyRequest())`.
- **Saloon features** — the connector is a regular Saloon connector: middleware, retries, caching plugins and mock clients all work as documented at [docs.saloon.dev](https://docs.saloon.dev).
- **Raw responses** — skip DTOs entirely with `->json()` when you need something the DTOs don't model.

🧪 Testing
---------

[](#-testing)

```
composer test
```

Tests use Saloon's `MockClient` with recorded fixtures — no live API calls, no API key needed.

The test suite also demonstrates how to mock the SDK in your own app:

```
use Chronoarc\Comicvine\Requests\GetIssueRequest;
use Saloon\Http\Faking\MockClient;
use Saloon\Http\Faking\MockResponse;

$mockClient = new MockClient([
    GetIssueRequest::class => MockResponse::fixture('valid_single_issue'),
]);

$comicvine = new Comicvine('fake-key');
$comicvine->withMockClient($mockClient);
```

🤝 Contributions Welcome
-----------------------

[](#-contributions-welcome)

Your feedback and contributions are highly appreciated! Whether it's submitting an issue, suggesting improvements, or adding new features, every bit helps make this SDK better for everyone.

---

Feel free to fork the repository, make pull requests, or just share ideas! Let's make this SDK awesome together.

###  Health Score

42

—

FairBetter than 88% of packages

Maintenance90

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~594 days

Total

2

Last Release

46d ago

Major Versions

0.0.1 → 1.0.02026-07-03

### Community

Maintainers

![](https://www.gravatar.com/avatar/f925a697449ab18af5a1d0b8aa406703b229ccc70bfd6e8216486fbba8ecee29?d=identicon)[fakeheal](/maintainers/fakeheal)

---

Top Contributors

[![fakeheal](https://avatars.githubusercontent.com/u/1038697?v=4)](https://github.com/fakeheal "fakeheal (17 commits)")

---

Tags

comicvinecomicvine-apiphpsdkphpsdkcomicvine

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/chronoarc-comicvine/health.svg)

```
[![Health](https://phpackages.com/badges/chronoarc-comicvine/health.svg)](https://phpackages.com/packages/chronoarc-comicvine)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)