Inertia Bundle Laravel Package

Technical Evaluation

Architecture fit

• This is a server-side PHP adapter for the Inertia.js protocol, explicitly tracking inertia-laravel 3.x as its reference implementation (the fix notes cite PropsResolver parity). Its value is highest where the backend is PHP but not Laravel (the -bundle naming and docs set point to a Symfony-style integration), or where a team needs a framework-light serializer that mirrors Inertia's wire contract.
• On a standard Laravel estate, inertia-laravel remains the default; this package is then a parity reference and a fallback, not a primary dependency. That distinction should be settled before we invest in it.
• v3.1.1 is a patch with no public API changes, so architectural fit is unchanged from v3.1.0 — what changed is protocol fidelity, not surface area.

Integration feasibility

• Low effort: Composer version bump, no migration steps in application code. All three fixes are wire-format/behavior conformance corrections rather than new capability.
• The work is verification, not implementation: snapshot the outgoing page payloads (merge/prepend/deep-merge/match props, deferred props, scroll props, once props, errors) and diff them across the bump.

Technical risk

• once()->until() expiresAt moved from seconds to milliseconds. This is described as a bug fix, and it is — but any consumer that parsed or persisted expiresAt (SSR layer, edge cache rules, custom prop caches, test fixtures) now reads a value ~1000× larger. Treat as a silent behavioral change despite "no breaking changes."
• Empty errors now serializes as {} instead of []. Any test asserting array shape, or front-end code doing .length / Array.isArray() on errors, will behave differently. Low blast radius, high likelihood of hitting a naive assertion.
• X-Inertia-Reset keys are now omitted from mergeProps/prependProps/deepMergeProps/matchPropsOn. Correct per protocol, but apps that implicitly relied on the old merge-into behavior for list accumulation (infinite scroll, paginated merge props) will see the client value replace rather than grow. This is the highest user-visible risk in the release.
• Documented "known gaps with inertia-laravel 3.x" confirm the package trails its own reference spec. Expect recurring parity patches of this shape; budget for them rather than treating this as a one-off.
• Single-maintainer project (nytodev) with a narrow contributor base — bus-factor and long-term support risk remains the dominant technical concern, not this patch.

Key questions

• Which runtime are we actually committing to — Laravel or Symfony/other PHP? The answer determines whether this package is load-bearing or reference-only.
• Which @inertiajs client version do we pin, and does it implement the millisecond expiresAt comparison and {} errors shape? Server and client must move together.
• Does anything in our stack parse expiresAt, or assert on the errors JSON shape?
• Do we have contract tests for reset/merge/once/errors, or is protocol drift currently caught by users?
• Who owns the upgrade cadence against inertia-laravel releases?

Integration Approach

Stack fit

• PHP 8.x + Composer; pairs with any Inertia client (Vue/React/Svelte). Fits cleanly alongside a Symfony or framework-agnostic PHP application; on Laravel it overlaps with inertia-laravel and should not be dual-adopted without a specific reason (e.g., a shared package serving both backends).
• Documentation changes here (docs/props.md, CLAUDE.md, AGENTS.md) also make the repo viable for AI-assisted contribution — relevant if we plan to carry patches upstream ourselves.

Migration path

• v3.1.0 → v3.1.1: version bump only. No code edits.
• Coming from inertia-laravel or a custom adapter: port per prop category — merge/prepend/deep-merge/match-on, deferred, scroll, once, errors. Note lazy()/LazyProp no longer exist; use optional(). This is the single largest source of mechanical edits, and the docs cleanup in this release makes the requirement unambiguous.
• If we are already on this package, the migration is behavioral, not structural: validate anything that depended on the old reset-merge semantics.

Compatibility

• Requires a client that compares expiresAt against Date.now(). Against an older client, the fix is inert — once() props will still re-resolve every visit. Confirm client version before claiming the performance benefit.
• The errors: {} change is protocol-conformant and matches inertia-laravel; older clients that tolerated [] should still work, but our own tests may not.

Sequencing

1. Stand up a payload contract-test suite (snapshot JSON for reset, merge, once()->until(), empty errors).
2. Bump to v3.1.1 in staging; diff payloads against v3.1.0 snapshots; review every diff intentionally.
3. Manually exercise merge/reset flows — infinite scroll, paginated lists, deferred props — where replacement vs. accumulation is user-visible.
4. Canary to production behind a small traffic slice; watch prop payload sizes and per-visit query counts.
5. Pin the version and add automated dependency PRs with the contract tests as the merge gate.

Operational Impact

Maintenance

• Low carrying cost per release, but a standing obligation: this package's correctness is defined by another project's changelog. Assign explicit ownership of tracking inertia-laravel releases, otherwise parity gaps accumulate silently.
• The contributor-docs refresh (test naming aligned to php-cs-fixer, stale lazy() references removed) lowers the cost of contributing fixes back — worth using if we hit a gap that blocks us.

Support

• Expect two post-upgrade ticket clusters: "my merged list lost its accumulated state" (reset now replaces) and, less likely, tooling that consumed expiresAt in seconds. Pre-write both into the release note we send to app teams.
• X-Inertia-Reset behavior is now documented explicitly; point support at docs/props.md rather than re-deriving it.

Scaling

• Server-side prop resolution stays stateless; no new scaling constraints.
• The once()->until() fix should reduce load: previously every until() prop looked expired, so it re-resolved on every visit. Expect a measurable drop in per-request query/API count on repeat visits for apps using once() — worth instrumenting to confirm the gain rather than assuming it.
• Correct X-Inertia-Reset also bounds client-side prop growth on merge props, which matters for long-lived sessions and payload size on paginated views.

Failure modes

• Silent wire-format divergence from inertia-laravel (this release fixed three such divergences; assume more exist until the documented gaps close).
• Client/server clock skew affecting until() expiry, especially with server-side rendering or queued workers generating props.
• Assumption mismatch on reset semantics producing duplicate or vanished list items in production rather than a test failure.
• Cache layers persisting expiresAt in the old unit after upgrade.

Ramp-up

• Roughly one sprint for a competent PHP engineer already familiar with Inertia concepts; materially longer for a Laravel-only team that has to learn the bundle's wiring and service configuration.
• The refreshed contributor docs shorten onboarding and make the contract-test suite the durable artifact that keeps ramp-up cost from recurring on every parity patch.