Tv Maze Php Api Laravel Package

Technical Evaluation

Architecture fit. dariusiii/tv-maze-php-api is a thin, unopinionated PHP wrapper around the public TVMaze REST API (show metadata, episodes, cast, schedules). Despite being evaluated in a "Laravel/PHP" context, it should be treated as a plain PHP HTTP client, not a framework-native package. There is no evidence of a Laravel service provider, facade, config file, or publishable assets. Architecture fit is therefore conditional: it works well as an infrastructure adapter underneath our own domain layer (a ShowCatalogClient interface), but it should not leak into controllers or jobs. TVMaze itself is a free, unauthenticated, read-only API for essentially static catalog data—this is a low-complexity integration by nature. Release 2.0.6 does not change this assessment in any way: it is a one-line internal cleanup, not a feature or structural change.

Integration feasibility. High. Composer install, instantiate the client, call a method, map the response into our own DTOs. The realistic effort is measured in hours, not days, and most of that effort is mapping and caching rather than the wrapper itself. The genuine question is not "can we integrate it" but "why not call the API directly"—the answer is convenience, and that convenience must be weighed against taking a dependency on a single-maintainer package. 2.0.6 is a patch release with no API surface change, so it introduces no migration work.

Technical risk. The dominant risk remains supply chain, not technology. Zero stars, zero dependents, and a single maintainer mean effectively no community verification, no peer review, and no realistic expectation of prompt security patches or API-drift fixes. 2.0.6 is a marginal positive signal on the abandonment axis: the maintainer merged an external contributor's PR (the first evidence we have of anyone other than the author touching the code) and did so promptly enough to address a PHP-level deprecation. That is a data point, not a track record—it does not upgrade the package to "supported," and it does not retire the fork-or-replace contingency.

More usefully, 2.0.6 resolves one of our open technical questions: removing curl_close() confirms the transport is hand-rolled cURL, not Guzzle and not PSR-18/PSR-17. Consequences:

• No PSR-18 interchangeability. We cannot inject a PSR-18 client, so we cannot reuse our standard Guzzle middleware stack (retry, logging, circuit breaking) at the package boundary. Any resilience behaviour must be wrapped around the adapter, or the wrapper must be swapped for Http::retry(...).
• No framework-level observability. Laravel's Http facade gives us event hooks and request logging for free; cURL calls inside the package are opaque unless the package exposes hooks. Assume we get none and instrument at the adapter boundary instead.
• No shared connection pooling or timeout policy. Timeouts and connection reuse are whatever the package hardcodes; we must verify this in the spike rather than assume.

Secondary risks unchanged: absence of a documented rate-limiting/backoff strategy (TVMaze enforces roughly 20 requests per 10 seconds and returns HTTP 429), and no stated caching story—significant because TVMaze data changes slowly and cache misses are the main cost driver. The upside of a thin wrapper is low lock-in: replacing it with Guzzle or Laravel's Http facade is a contained refactor, and the cURL discovery slightly strengthens the case for ultimately doing so.

Key questions.

• Does it cover the specific endpoints we need (search, shows/:id, shows/:id/episodes, schedule), or only a subset?
• Is HTTP transport PSR-18/PSR-17 compliant, or hard-wired to Guzzle? Answered by 2.0.6: hand-rolled cURL. Follow-up: are timeouts, connect timeouts, and TLS verification configurable, given we cannot inject our own client?
• Does it implement retry/backoff and 429 handling, or pass failures straight through? (Now more consequential—no middleware stack to fall back on.)
• Are response objects typed DTOs, arrays, or raw JSON—and how tightly would we couple to them?
• Minimum PHP version and PHPUnit/modern PHP support (PHP 8.2+, strict types)? 2.0.6 addresses a deprecation that lands in PHP 8.5, which suggests recent-PHP awareness, but composer.json constraints still need verifying.
• Is there a test suite with recorded fixtures, and is CI green? Does the CI matrix cover the PHP versions we run?
• Security posture: any known advisories via composer audit, and does it pin third-party dependencies?

Integration Approach

Stack fit. Treat the package as an outbound adapter in a hexagonal layout. Define our own interface (CatalogProvider) in the domain, implement it with a TvMazeCatalogProvider that internally uses this wrapper, and bind it in a Laravel service provider we author ourselves. This inverts the dependency: we own the contract, the package is replaceable, and the rest of the application never imports a DariusIII\... class. The confirmed cURL transport makes this boundary more important, not less—it is the only place we can add retry, throttling, and logging.

Migration path. Because the wrapper is thin and TVMaze is a simple JSON-over-HTTP API, migration away from it is cheap—and now demonstrably cheaper than we assumed, since there is no PSR-18 abstraction to preserve. A pragmatic default: prototype with the wrapper behind our interface, and if the wrapper adds friction (untyped responses, no retry, non-configurable timeouts), implement the same interface directly with Http::retry(...) and drop the dependency. Either way, the interface is the durable artifact. Note that 2.0.6 is a drop-in patch: if anyone has already pinned 2.0.5 in a spike branch, bumping is a no-op with no code changes required.

Compatibility. Verify PHP version alignment with our runtime before committing. 2.0.6 removes a call that is deprecated in PHP 8.5 (and has been a no-op since 8.0), which tells us the maintainer is tracking current PHP—a mild compatibility positive—but we should not infer a declared support matrix from a single PR. Wrap all responses in our own DTOs and validation so that upstream field changes surface as mapped errors rather than silent nulls. Do not serialize package objects into cache or queues—cache our DTOs instead, or the package's internal shape becomes a de facto schema.

Sequencing.

1. Spike: install (2.0.6), exercise each required endpoint, and confirm response typing, timeout configurability, and error behavior (~0.5 day).
2. Define CatalogProvider interface and DTOs; implement adapter over the wrapper.
3. Add a Laravel service provider, config (base URI, timeout, retry), and Http-level or cache-level middleware. Because transport is cURL, assume retry/throttle lives in our adapter unless the spike proves otherwise.
4. Introduce a caching layer keyed by endpoint+params with a TTL measured in hours to days; TVMaze data is near-static.
5. Add contract tests against recorded fixtures, plus a smoke test against the live API in a non-blocking CI job.
6. Run composer audit and pin the version explicitly in composer.json—pin to 2.0.6 or a ^2.0 constraint, and adopt patch releases deliberately rather than floating.

Operational Impact

Maintenance. Low ongoing cost if the interface boundary is respected, because replacing one small adapter is trivial. The real cost is ownership ambiguity: with zero dependents, we are almost certainly the only production consumer, meaning we are de facto maintainers of our integration and cannot expect upstream fixes. Budget a small recurring allowance for dependency review and a fork-or-replace decision at each major PHP or Laravel upgrade. 2.0.6 is a good template for what upstream maintenance looks like in practice—small, contributor-driven, deprecation-driven cleanups with no roadmap—and it is a reminder that our own dependency-review cadence, not theirs, is what keeps this healthy.

Support. No community, no issue-tracker track record, no vendor. Support falls entirely to our team. This is acceptable for a non-critical, read-only catalog integration and unacceptable anywhere near revenue or auth paths. Document the internal owner and the replacement plan in the service's README. The appearance of one external contributor in 2.0.6 is not a support channel and should not be treated as one.

Scaling. TVMaze is a third-party free API with no SLA; our scaling is bounded by their rate limits, not ours. The mitigation is aggressive caching plus request coalescing: catalog reads should hit cache, not the network. Introduce a queue/throttle if bulk ingestion is needed, and treat the upstream as a derived source—persist what we need locally rather than serving user traffic through live calls. Latency and availability of the feature are then a function of our data store, not TVMaze's uptime. The cURL transport confirmed in 2.0.6 means we cannot lean on a shared connection pool from a framework client, so connection-level efficiency is another reason to keep the network path cold.

Failure modes.

• HTTP 429 from TVMaze — no built-in backoff means bursts cascade into user-visible failures; enforce client-side throttling, and note that with cURL transport we cannot drop in PSR-18 retry middleware.
• Silent schema drift — TVMaze changes or nulls a field; untyped responses propagate null into the UI. Mitigate with DTO validation and alerting on mapping failures.
• Maintainer abandonment — no upstream patch for a breaking API change; our adapter is the blast radius, so keep it small. Slightly reduced but not eliminated by the activity seen in 2.0.6.
• Dependency/security advisory — no upstream patch path; requires us to fork or pin and vendor.
• PHP-version deprecation drift — 2.0.6 shows the package will accumulate language-level deprecations between releases; unaddressed ones surface as noisy logs or, in strict configurations, errors. Track our PHP upgrade dates against upstream releases and be prepared to patch locally.
• Cold-start latency — first uncached calls are slow; pre-warm popular entries and set a timeout with graceful degradation (serve stale data).

Ramp-up. Very low for an engineer familiar with HTTP clients: the TVMaze API is well documented and the wrapper is small enough to read end to end in under an hour—and now slightly smaller than the 2.0.5 we reviewed. The learning investment belongs in the interface and DTO layer we author, not the package. Write a short internal integration note covering rate limits, cache TTLs, the cURL transport constraint (no PSR-18 injection), and the replace-the-adapter runbook so that ramp-up survives maintainer turnover. Overall recommendation unchanged: adopt conditionally—behind an internal interface, with caching and throttling, on non-critical paths only, and with a documented exit plan. 2.0.6 requires no action beyond pinning to it; it is a minor positive signal on maintenance hygiene and a clarifying one on transport coupling, neither of which moves the recommendation.