Thetvdbapi Laravel Package

Technical Evaluation

Architecture fit. canihavesomecoffee/thetvdbapi is a thin, framework-agnostic PHP wrapper around an external HTTP service (TheTVDB v2). That is the right shape for Laravel: it has no opinion about our container, ORM, or routing, so it can live behind an adapter in the infrastructure layer while our domain models stay clean. It should be treated as a transport client, not as a data source of record — TheTVDB enriches our catalog, it does not own it.

Integration feasibility. Mechanically straightforward: composer require, a config file for the API key, a singleton binding in a service provider, and a small mapping layer from package response objects to our DTOs/Eloquent models. Expect roughly 1–2 developer-days for a first vertical slice (search → series → episodes → artwork) including caching, assuming the package exposes the endpoints we need and does not impose hard-coded Guzzle versions that collide with Laravel's HTTP client stack.

Technical risk — HIGH. Several independent concerns stack up:

• API version risk (dominant). TheTVDB v2 is the legacy API surface; v4 is the current generation (JWT/API-key auth, revised endpoints and rate limits). A wrapper pinned to v2 inherits whatever sunset policy TheTVDB applies to v2. This is the single largest risk and it is outside our control.
• Supply chain. 10 stars, repository: unknown, ISC license, single-maintainer profile. Provenance is unverified, so it needs a source review and ideally a vendored fork before it touches production. The 2025-12-17 release date is reassuring but could be a metadata/composer bump rather than functional work.
• Coverage risk. Wrappers of this size typically cover the popular endpoints (search, series, episodes) and stop there. Artwork, translations, absolute-ordering episodes, and update feeds are frequently the gaps — and those are exactly what a catalog pipeline needs.
• Blast radius is contained if we isolate it behind our own interface, which is the mitigation that makes this acceptable at all.

Key questions.

1. Does TheTVDB v2 still serve our required endpoints under our account tier, and for how long? What is the vendor's stated v2 deprecation posture?
2. Does the package support artwork, translations, episode ordering (aired vs absolute), and the /updates delta feed?
3. What are the package's PHP and Guzzle/PSR-18 constraints, and do they conflict with our Laravel version?
4. Is there a test suite, and does it mock HTTP or hit the live API?
5. Can we fork and maintain it internally if the maintainer disappears? (Assume yes; budget for it.)
6. Is there an alternative — a maintained v4 client, or 150 lines of our own Guzzle code against v4 — that removes the dependency entirely?

Integration Approach

Stack fit. Works with Laravel 9–12 on PHP 8.x provided Composer resolves cleanly; verify the Guzzle major version and any illuminate/* hints before committing. Bind it as a singleton in a dedicated service provider, publish config for api_key/token, and expose our own TvdbGateway interface in front of it. Nothing outside the adapter layer should ever import a package class.

Migration path. Adopt behind the interface from day one, even for the initial spike:

• App\Contracts\TvdbGateway — our verbs (searchSeries, getSeries, getEpisodes, getArtwork), not the package's.
• App\Services\Tvdb\CanIHasSomeCoffeeAdapter — the only file that references the package.
• DTOs mapped explicitly; no package response objects crossing the boundary.

If v2 is retired or the package is abandoned, the replacement is one class plus a container binding, not a refactor.

Compatibility. Check the Composer constraint matrix first (PHP floor, Guzzle major, PSR-18/17 discovery). If the package bundles a fixed HTTP client, it will bypass Laravel's HTTP client middleware — meaning no built-in retry, logging, or tracing. Plan to wrap calls in our own retry/timeout policy at the adapter level rather than relying on the package.

Sequencing.

1. Vendor/source review and legal sign-off on ISC; fork into the org namespace and pin the commit.
2. Authenticated spike against a sandbox API key — prove the four endpoints we care about and record real payloads.
3. Adapter + config + cache layer merged with feature flag off.
4. Queued ingestion jobs (search, then hydrate, then artwork) behind the flag.
5. Observability (latency, error rate, rate-limit headers) before enabling for real traffic.
6. Parallel track: sketch a v4 client so the contingency has a head start.

Operational Impact

Maintenance. Low change velocity, low ceremony — composer update plus quarterly advisory review. The real cost is ownership, not upgrades: assume we are the de facto maintainers of a fork. Budget 1–2 days per quarter plus a defined owner. Pin exact versions in composer.lock; never float this dependency.

Support. No vendor support. Upstream is GitHub issues with a single maintainer — treat response time as unbounded. Establish an internal escalation path (fork → patch → upstream PR) before the first incident, and document that TheTVDB's own API status/support channel is our primary external dependency, not the package author.

Scaling. TheTVDB enforces rate limits and returns 429s; the wrapper will not solve that for us. Design accordingly: read-through cache with per-entity TTLs (series metadata days, artwork URLs hours, /updates delta polling minutes), background queue for bulk hydration, and strict avoidance of per-episode fan-out calls in request paths. Expect the cache to absorb 90%+ of reads; if it does not, the integration is misdesigned, not underscaled.

Failure modes to instrument.

• Auth/token expiry — silent 401 loops are the classic failure; alert on auth errors specifically, not just 5xx.
• Rate limiting (429) — surface remaining-quota headers into metrics, back off with jitter.
• Upstream 5xx / outage — degrade to cached data, never block the user-facing read path.
• Missing or removed series (404) — must be a normal, logged, cached-negative outcome, not an exception that pages someone.
• Artwork URL drift — TheTVDB returns relative paths that change; store the path, not the resolved URL, and resolve at render time.
• Schema drift — the wrapper may not validate responses; add a contract test against recorded fixtures so upstream changes fail loudly in CI.
• Stale cache poisoning — if a bad payload is cached, TTLs become an outage duration. Validate before write.

Ramp-up. Trivial for any PHP developer to call; the actual onboarding cost is domain knowledge — TVDB ID semantics, aired vs absolute episode ordering, and the difference between series-level and episode-level artwork. Budget a half-day of documentation with recorded fixtures so the next engineer never has to hit the live API to understand the integration.

Recommendation. Conditional go: acceptable as a time-boxed accelerator only behind our own interface, vendored/forked, and with a v4 client spike scheduled in the same quarter. If the spike shows the package does not cover artwork and delta sync, skip it and write the v4 client directly — a 10-star v2 wrapper is not worth owning when the API generation underneath it is already one behind.