Json Laravel Package

Technical Evaluation

Architecture fit

• psx/json is a Composer-installable, PSR-4, framework-agnostic library implementing JSON-Pointer (RFC 6901) and JSON-Patch (RFC 6902) primitives over decoded PHP documents. It is a leaf utility, not an HTTP, ORM, or container component, so it slots under Laravel without fighting the framework.
• It has no Laravel service provider, facade, config file, or validation rule set. Treat it as an internal capability you wrap: a JsonPatchService contract bound in a small JsonServiceProvider, with PSX classes confined to the adapter layer.
• Best-fit surfaces in a typical Laravel product: application/json-patch+json and merge-patch PATCH endpoints, delta storage for audit/event-sourced records, multi-tenant config layering (base document + tenant patches), webhook payload reshaping, and ruleset/feature-flag document mutation.
• Poor fit for: streaming or very large documents (it is an in-memory tree operation), binary/media transforms, or anything requiring schema validation — patch and schema are separate concerns and you would pair it with a validator.

Integration feasibility

• Installation cost is effectively zero (composer require psx/json). The real cost is containment, test coverage, and an exit path.
• The API surface is small enough to fully wrap in a day, which caps the blast radius of the low-adoption signal.
• Verify the transitive dependency graph before committing: PSX components have historically pulled sibling packages (psx/data, PSR-7/PSR-17 abstractions). If those arrive with you, you inherit version constraints that can collide with Laravel's own PSR pins.

Technical risk

• Adoption risk (high): 5 GitHub stars, 0 dependents, and a low composite score indicate near-zero external usage. There is no community to catch regressions and no downstream pressure to keep it current.
• Bus factor (high): single-maintainer project inside the Apioo/PSX ecosystem. If the maintainer's priorities shift, releases stop.
• Mitigation is real, not theoretical: Apache-2.0 plus a small, RFC-anchored surface means a fork-and-vendor strategy is viable. The RFCs are the spec; the code is replaceable. This materially downgrades the risk versus a large, license-encumbered dependency.
• Correctness risk (medium): patch semantics have sharp edges (pointer escaping ~0/~1, - array append, test op atomicity, move/copy aliasing). These are library-agnostic, but a low-traffic library gets fewer bug reports against them.
• Ecosystem fit (medium): PSX packages can lag PHP minor versions. Confirm the php constraint against your Laravel/PHP baseline before the spike, not after.

Key questions

1. Which RFCs and versions are actually implemented — 6901, 6902, merge-patch (7386), JSON-LD? Is the "transform" in the description Patch-based or a separate transformer we would be depending on?
2. What is the full composer why-level dependency tree, and does it constrain PHP, PSR, or PHPUnit versions relative to Laravel 10/11?
3. Does patch application fail atomically on a failed test operation, or can it leave a partially mutated document? This determines whether we can trust it for writes.
4. How are PHP's array/object ambiguities handled — numeric string keys silently cast to integers, empty objects vs empty arrays, and large-number precision?
5. Is there a runnable conformance suite we can point at the RFC 6902 appendix examples, or do we build that harness ourselves?
6. What is the maintainer's stated support policy, and how many releases in the last 24 months?
7. Have we benchmarked swaggest/json-diff (patch + pointer + merge-patch, actively maintained) as the default alternative? The decision should be "PSX wins on X," not "PSX was first in the search results."

Integration Approach

Stack fit

• Ship it as an internal capability, never as a direct call from controllers, models, or jobs. One JsonPatchApplier interface, one PSX-backed implementation, one binding. Everything else in the codebase depends on the interface.
• Normalize at the boundary: decode with JSON_THROW_ON_ERROR, reject non-object/array roots for patch targets, and return a domain result object rather than raw arrays or PSX exceptions.
• Pair with Laravel's validation for envelope shape (Content-Type, array of operations, op allowlist) so malformed patches fail at the edge rather than deep in the applier.

Migration path

• Phase 0 — spike (2-3 days): a throwaway branch that runs the RFC 6902 appendix examples plus 20-30 redacted production payloads through the library. Gate on pass rate and on any PHP-version or dependency friction.
• Phase 1 — adapter: land the interface, the PSX implementation, and a NullJsonPatchApplier/array-diff fallback implementation behind the same contract. Feature-flag selection via config. This is the exit ramp and it is cheap now, expensive later.
• Phase 2 — new surfaces only: introduce patch endpoints and delta-storage for new resources. Do not retrofit existing full-document PUT/PATCH handlers in this phase.
• Phase 3 — retrofit and event sourcing: migrate legacy update handlers once the adapter has run in production for a quarter; then consider adopting patches as the canonical audit delta format.
• Avoid a big-bang replacement of array_merge/recursive-replace logic. Those are load-bearing and often encode undocumented business rules that JSON-Patch semantics will not reproduce.

Compatibility

• Verify php constraint vs. your Laravel baseline (Laravel 10 → PHP 8.1+, Laravel 11 → 8.2+). If the package trails, pin and schedule the upgrade separately from the framework upgrade.
• Run composer require --dry-run first and read the resolution output for PSR/PHPUnit downgrades. A test-tooling downgrade is a hidden tax on the whole repo.
• Check whether PSX exceptions implement PSR container interfaces you would need to translate; if the library throws its own hierarchy, wrap it so the vendor namespace does not leak into error-handling contracts or API responses.

Sequencing

1. Dependency and PHP-constraint audit (blocks everything).
2. RFC conformance harness — build this first; it doubles as the acceptance test for any alternative implementation.
3. Interface + adapter + feature flag.
4. First production surface (single PATCH endpoint, low-traffic resource).
5. Benchmark against swaggest/json-diff on your real payload sizes; revisit the build-vs-buy call before broadening adoption.
6. Retrofit legacy handlers only after the adapter has a clean quarter.

Operational Impact

Maintenance

• Budget a recurring line item for dependency stewardship: monthly composer audit and composer outdated review, and a documented policy that the vendored fork is refreshed at least annually. Pin exactly (composer.lock) and never allow floating constraints on this package.
• Assume you will eventually fork. Do the small work upfront to keep it cheap: keep patches confined to the adapter, never subclass PSX internals, and record in an ADR why the package was chosen.
• Apache-2.0 is permissive and clean for commercial use; attribution and NOTICE obligations are trivial but should be captured in your third-party license inventory now, not at audit time.

Support

• There is no commercial support, no vendor SLA, and effectively no community. Internal ownership is mandatory: name a code owner for the adapter and the fork.
• Ramp-up documentation should be two pages: which RFCs you rely on, which operations you permit, and where the adapter boundary sits. The RFCs are public and readable, which makes onboarding unusually easy for a dependency of this risk profile.
• Because the library is standards-backed, "support" partially means "the spec is stable." That is the strongest argument in its favor and should be stated explicitly in the ADR.

Scaling

• Complexity is proportional to patch size times pointer-resolution depth, and both are bounded by payload design, not concurrency. Expect linear and predictable.
• The real ceiling is memory: the whole document is decoded into a PHP tree before mutation and re-encoded after. Budget roughly an order of magnitude of overhead versus raw JSON size, and set a hard request-size limit at the edge.
• For high-volume delta storage, patches reduce write amplification dramatically (a one-field change becomes tens of bytes instead of the full document). That is the primary scaling win and it is the reason to adopt the library at all.
• Where throughput matters, patches are cheap to apply but you should not apply long patch chains to rebuild state on every read — snapshot periodically.

Failure modes

• Non-atomic application: a failed test op mid-patch could leave a half-mutated document. Confirm the library aborts cleanly; if not, apply to a deep copy and swap on success. This is the highest-severity failure mode because it silently corrupts writes.
• PHP array semantics: numeric string keys cast to integers and empty objects decode as empty arrays. A pointer that should address {"0": ...} can silently hit array index 0. This is a data-integrity bug, not a crash, and it is the one most likely to reach production.
• Pointer escaping: unescaped ~ and / in keys produce not-found errors that surface as 400s to customers. Centralize pointer encoding and test it.
• Numeric precision: JSON numbers beyond IEEE-754 or PHP int range lose precision through decode/encode. Financial and ID fields need string encoding at the boundary.
• Partial-schema drift: the library patches structure but validates nothing. Without a schema check after apply, you can persist a structurally invalid document. Pair with a validator and treat the post-patch validation as a mandatory step.
• Abandonment: the failure here is not an outage, it is an inability to get an upstream fix for a PHP 8.x incompatibility. The vendored-fork plan is the mitigation; test the fork path once, deliberately, so it is proven when you need it.

Ramp-up

• Two to three days for a mid-level PHP engineer to be productive: RFC 6901 is a page, RFC 6902 is a handful of operations, and the adapter surface is small.
• The steeper learning curve is not the library — it is deciding which API surfaces should accept patches. Restrict patchability to resources with clear ownership and a stable pointer contract; exposing patch on deeply nested, rapidly evolving schemas creates a client-facing compatibility burden you cannot easily walk back.
• Recommend a one-hour brown-bag on patch semantics (atomicity, test-op, escaping, array append) before the first endpoint ships. Most production incidents with JSON-Patch come from client misunderstanding of replace vs add and from array index assumptions.

Verdict Low integration cost, credible technical fit, and a genuinely valuable capability (delta storage, standards-compliant PATCH) against a weak adoption and maintenance signal. The package is defensible only behind a thin internal interface with a tested fallback and a fork plan. Approve for a bounded spike on one low-traffic surface; make the broader commitment contingent on the conformance results and a head-to-head against swaggest/json-diff on your own payloads.