Laravel Package Laravel Package

Technical Evaluation

Scope of this update — 3.0.0 is a breaking major. The release changes the supported-version matrix, which is the single most decision-relevant attribute of a framework integration package. Three findings matter, in order of importance:

1. The release notes contradict themselves. "Restore support for Laravel 8, 9 and 10 ([PR#37])" sits directly alongside "Dropped support for PHP 7.2 and 7.3 and Laravel 5.5 through 10. Minimum supported PHP version is now 7.4 and minimum supported Laravel version is now 11." These cannot both be true. The stated PHP floor of 7.4 is also inconsistent with a Laravel 11 floor, since Laravel 11 requires PHP 8.2. Treat the prose as unreliable and read composer.json directly — this is now a mandatory step, not a nice-to-have. Note also that 3.0.0 simultaneously raises the floor to Laravel 11 and adds Laravel 13 support; if Laravel 13 is not yet GA, that is forward-looking CI wiring, not a supported configuration you can run today.
2. Laravel 13 support is a genuine positive signal. It is the clearest evidence yet that the maintainer intends to track framework majors rather than let the wrapper rot. This partially de-risks the "breaks on framework major" failure mode flagged previously.
3. Maintenance process has been formalised — changelog automation, release automation, and a CI hygiene pass (actions/checkout v2 → v6). A Copilot agent workflow was also added. Read together, this is a small maintenance-maturity improvement; read sceptically, it suggests AI-assisted or low-touch maintenance, which does not change the underlying bus-factor of one or two people. Automation of changelogs is not a substitute for a second maintainer.

Architecture fit. Unchanged. json-mapper/laravel-package remains a thin integration shell around the framework-agnostic json-mapper/json-mapper core — service provider registration, JsonMapperInterface container binding, publishable config for the middleware stack, and a facade. That shape is correct for a Laravel integration, and the disposable-framework-glue property is what makes this release survivable: if 3.0.0 does not fit your Laravel version, you can reproduce the wrapper against the core in 20–30 lines. The core library remains the real dependency and is not addressed by this release at all.

Integration feasibility. Still high, but no longer a one-step install. If you are on Laravel 8, 9, or 10, you must either stay on the 2.x line, confirm the "restored" 8/9/10 support actually exists in the 3.0.0 constraint (contradicted by the notes), or write the adapter against the core directly. If you are on Laravel 11 or 12, adoption is straightforward. No queue, asset, route, or migration footprint — that has not changed.

Technical risk. The code risk remains low, but 3.0.0 adds a new category: release hygiene risk.

• Code risk: low. Small surface area, MIT, active cadence.
• Ecosystem risk: high and unchanged. 25 stars, zero dependents, no external validation, no crowd-sourced bug discovery. Nothing in this release changes that.
• Release hygiene risk (new): self-contradictory breaking-change notes on a major version. That is a process defect, not a typo — it means the documented compatibility surface cannot be trusted without reading source. It also means the next upgrade needs the same manual verification. Weigh this accordingly: it is a small team shipping without a second reviewer, and it will happen again.

Key questions for the maintainer / spike (revised):

• What is the literal illuminate/support constraint in 3.0.0, and what does the CI matrix actually test? Resolve the 8/9/10 contradiction before anything else.
• Is the PHP floor 7.4 or 8.2? The notes and the Laravel 11 requirement disagree.
• Is Laravel 13 released or pre-release, and is "support" tested against it or merely declared?
• Did 3.0.0 change any runtime behaviour beyond the constraint bump — middleware defaults, singleton vs. transient binding, config keys? Confirm by diffing source, not changelog.
• Which Laravel versions are in CI today, and what is the stated policy for the next major?
• Does it support PHP 8 attributes, docblock annotations, or both?
• Is the middleware stack configurable per-resolution or only globally via config?
• Failure semantics for unknown key, missing key, and type mismatch — verify empirically.
• Are mapping exceptions translated into anything Laravel-native, or does JsonMapper\Exception\JsonMapperException propagate raw?
• Is reflection metadata cached across requests or recomputed per hydration?
• What did the Copilot agent workflow change about how contributions are reviewed? (Signals whether an outside PR would be meaningfully reviewed.)

Integration Approach

Stack fit. Narrowed. The package is now appropriate for Laravel 11+ on PHP 8.2+ (subject to the contradiction above), and the previous "Laravel 9+, PHP 8.1+" statement should be retired. If any service in scope runs Laravel 10 or earlier, it is on a different integration path and should be treated as a separate decision, not a version constraint to negotiate around. Use cases are unchanged: integration boundaries where JSON crosses into typed application code. Still a poor fit for Eloquent serialization or public API response layers.

Migration path. Unchanged and still the highest-leverage decision: adopt behind an application-owned port (App\Support\Mapping\JsonHydrator) with a thin adapter delegating to the package. This matters more after 3.0.0 than before it, because it is the mechanism that lets you absorb a package major without touching call sites — and it is now plausible you will need to. If you are on Laravel ≤10, skip the wrapper, write the 20–30 line provider against the core, and take the core dependency decision on its own merits.

Compatibility. Three checks now precede adoption:

1. Read composer.json for illuminate/support, php, and psr/container constraints and reconcile against your application and against the release notes. Do not proceed on the prose.
2. Confirm no collision on the JsonMapperInterface binding with existing providers, and no php-di pin conflict.
3. Check whether 3.0.0 altered config keys or middleware defaults — a published config file from 2.x may silently change behaviour on upgrade.

Sequencing (revised):

1. Constraint verification (2 hours). Resolve the version-matrix contradiction from composer.json and CI config. This gates everything else and is cheap.
2. Spike (1–2 days). Install on a branch, hydrate two or three real production payloads — one nested array of objects, one with malformed/extra keys. Record actual behaviour. If upgrading from 2.x, run the same payloads against both majors and diff.
3. Comparison gate (unchanged). Benchmark against a hand-written hydrator and spatie/laravel-data. The incumbent's ecosystem advantage is unchanged; JsonMapper's differentiators remain the middleware pipeline, no code generation, and lower per-hydration overhead.
4. Productionize. Adapter, config, exception translation, contract tests against recorded fixtures.
5. Roll out per boundary, with the adapter as the rollback seam.
6. Pin the major explicitly (^3.0) and record the reason in the ADR, so the next upgrade is a deliberate decision rather than a composer update side effect.

Operational Impact

Maintenance. Low ongoing effort, but the review cadence should tighten from quarterly to on every Laravel major and every package major. 3.0.0 is the concrete case for this: it was a breaking release whose own notes cannot be used to determine compatibility. Assume you may need to vendor or fork the wrapper — still cheap — and that the core remains the expensive thing to fork. The formalised changelog and release automation modestly reduce the chance of silent rot; they do not eliminate it.

Support. Unchanged: GitHub issues only, no commercial backing, no security response process, no CVE history. The addition of release automation and a CI refresh are operational hygiene, not a support commitment. The team still owns resolution. Do not place this where a mapping bug becomes a customer-facing outage with no internal expertise to fix it.

Scaling. Unchanged. Reflection-based hydration is CPU-bound and per-request; cost scales linearly with payload size and nesting depth. Singleton binding limits construction cost, not mapping cost. Benchmark high-volume ingestion endpoints before committing. Memory profile unremarkable.

Failure modes to design against:

• Version-matrix surprise (new) — installing 3.0.0 resolves against an unexpected Laravel/PHP combination because the documented floor is wrong or ambiguous. Mitigation: read composer.json, pin the major, run the spike on the exact target versions.
• Upgrade behaviour drift (new) — config keys or middleware defaults changed under the major bump without a documented migration path. Mitigation: diff source and published config between 2.x and 3.0.0; regression-test against recorded fixtures.
• Silent data loss — unknown JSON keys dropped without error. Dangerous where a new upstream field must be noticed.
• Silent coercion — "12" becoming 12; null and absent key collapsing to the same result. These masquerade as upstream data bugs for weeks.
• Untranslated exceptions — raw mapper exceptions escaping into API responses, leaking internals or returning 500s where a 422 belongs.
• Upstream schema drift — no built-in schema validation; a breaking upstream change surfaces as a type error deep in the call stack rather than at the boundary.
• Abandonment — no patches during a Laravel major cycle. Reduced but not eliminated by the Laravel 13 work.

Each still has a cheap mitigation: strict-mode configuration where available, contract tests over fixtures, explicit exception translation in the app handler, version pinning, and the adapter seam.

Ramp-up. Unchanged for a mid-level Laravel developer — roughly half a day to productivity, concentrated in mapping conventions and in debugging hydration failures where messages are less precise than a hand-written hydrator's. Add a caveat: the package's own release notes are not a reliable source of truth, so the engineer doing the spike must be comfortable reading composer.json, CI config, and provider source. Documentation quality remains unverified and should be assessed during the spike; budget for one engineer to become the internal reference.

Overall. Recommendation narrows to: proceed with the bounded pilot only if you are on Laravel 11+ and the composer.json constraints match the release notes. For teams on Laravel ≤10, the wrapper is no longer the right entry point — either stay on 2.x deliberately or integrate the core directly behind the adapter. The 3.0.0 release is net-positive on forward compatibility (Laravel 13, formalised release process) and net-negative on trust (contradictory breaking-change notes on a major). The underlying calculus is unchanged: small, technically sound, appropriately scoped, and unvalidated by anyone you can point to. The adapter seam remains the condition of adoption, and the core library — untouched by this release — remains the dependency actually being evaluated.