Json Api Common Laravel Package

Technical Evaluation

Architecture fit. enm/json-api-common is not a Laravel package and not even a standalone implementation — it is the framework-agnostic value-object and interface layer shared between enm/json-api-server and enm/json-api-client. It supplies the JSON:API vocabulary (resources, relationships, documents, links, errors, request/response abstractions) but no HTTP layer, no routing, no Eloquent mapping, no service provider, no config. In a Laravel app, adopting it means adopting the sibling server package and writing all the Laravel glue ourselves. Against Laravel-native options (laravel-json-api/laravel-json-api, Laravel's own Eloquent API Resources, or hand-rolled transformers), it carries no framework affinity. Its only genuine differentiator is strict JSON:API spec symmetry between a PHP client and a PHP server built on the same primitives.

Integration feasibility. Low to moderate. Composer install is trivial, but the package is archived (last release 2020-12-14) and its PHP constraint almost certainly predates PHP 8.1+ and Laravel 9–12 support. Expect to fork or pin. Zero public dependents means no ecosystem validation — we would be the first party exercising this code against a modern Laravel runtime.

Technical risk. High, concentrated in three areas:

1. Abandonment — no upstream security or bug fixes; every future PHP minor becomes our problem.
2. Spec drift — JSON:API has continued to evolve (atomic operations, updated error/link guidance); a 2020 implementation is spec-current as of 2020, not now.
3. Surface-area asymmetry — the "common" half is only valuable if both ends use it, which is rarely true for a Laravel backend serving SPA, mobile, or native clients.

Key questions.

• Is strict JSON:API compliance a hard, contractual requirement, or is a pragmatic REST shape acceptable?
• If strict: which spec version, and does the sibling server package still install cleanly on our PHP/Laravel matrix?
• Do we actually have a paired PHP client that benefits from shared structures, or is this a one-sided server need?
• Are we prepared to own a fork indefinitely — PHP 8.x/9.x compatibility, dependency advisories, spec updates?
• What is the three-year TCO of LaravelJsonApi or plain API Resources versus this path?

Integration Approach

Stack fit. Poor as a direct dependency; useful at most as a design reference. It assumes a PHP application that already has a JSON:API document model and wants typed structures for it. Laravel idioms are entirely absent, so integration cost lands on us: a service provider, config publishing, exception mapping into Laravel's handler, and serialization into JsonResponse.

Migration path. If we proceed, treat it as a spike, not a migration:

1. Branch-local composer require enm/json-api-common enm/json-api-server against our exact PHP/Laravel matrix.
2. Run the sibling packages' own test suites to confirm PHP 8 compatibility.
3. Implement one read-only resource end-to-end — a single collection with one relationship — and measure glue code volume.
4. Benchmark that LoC and complexity against the same endpoint built in LaravelJsonApi.
5. Decide. Do not plan a brownfield migration; this is greenfield or nothing.

Compatibility. Verify the composer.json PHP constraint against our runtime, PSR-7/PSR-17 dependency versions (likely ^1.0/^2.0, possibly legacy zendframework/*), and whether the server package's middleware can be expressed as Laravel middleware without rewriting. The Symfony HttpFoundation ↔ PSR-7 bridge is the likely friction point.

Sequencing. Only after the spike succeeds: fork to an internal namespace, pin a PHP CI matrix, add static analysis, write contract tests against the JSON:API spec, then wire a first production resource. Never adopt this as a transitive dependency of something we don't control.

Operational Impact

Maintenance. This is the dominant cost. Archived plus zero dependents means we inherit the entire maintenance surface — PHP version bumps, deprecation fixes, dependency security advisories — for a library of value objects we could otherwise write in a few hundred lines. Budget a named fork maintainer and a quarterly compatibility review.

Support. No upstream issue triage, no maintainer to escalate to. Internal documentation must replace the README, which is thin and now frozen (trait, resources, collections, links, documents, errors, requests). Onboarding cost is real: engineers must learn both this library's conventions and the JSON:API spec to use it correctly.

Scaling. A non-issue. The package is pure PHP data structures; CPU and memory cost is negligible relative to serialization and database work. It will never be the bottleneck — the surrounding server package and query layer will be.

Failure modes.

• Silent spec non-compliance producing subtly wrong payloads that clients only catch in edge cases.
• Hard breakage on a PHP minor bump, blocking framework upgrades.
• Drift between our fork and upstream that nobody remembers to reconcile.
• The shared-structure benefit evaporating because only the server side is PHP.
• Bus-factor collapse when the engineer who ran the spike leaves.

Ramp-up. Low for the API surface (a handful of interfaces and value objects); high for the context — JSON:API document/relationship/error semantics plus the sibling packages' conventions. Realistically one to two weeks for a mid-level engineer to become productive on a single resource, plus spec study. Given the score (1.79), archived status, and mature alternatives, expected value is negative unless strict JSON:API symmetry between a PHP client and a PHP server is a genuine, locked requirement.