Json Laravel Package

Product Decisions This Supports

• Feature delivery on JSON-backed models. Laragear/Json wraps JSON documents in a fluent, Laravel-native object so product surfaces that store semi-structured data (user preferences, per-tenant settings, form-builder schemas, third-party webhook payloads, feature-flag blobs) can read/write nested keys without bespoke array-walking code in every controller and job.
• Build vs. buy. The capability it replaces is small but ubiquitous — data_get/data_set scattered across the codebase, ad-hoc casts, and one-off normalizers. Buying a ~single-purpose package is cheaper than owning an internal helper that every team reimplements, provided the API surface stays stable.
• Roadmap sequencing for schema evolution. Because JSON columns change shape faster than migrations, a consistent accessor layer lowers the cost of iterative product changes: adding a field to a settings blob becomes a config change, not a migration plus backfill plus rollout.
• Risk scoping for a major-version upgrade (v4.0.0). A semver-major bump is a planning input, not a feature. Treat this release as a compatibility audit gate: schedule an engineering spike to diff v3.0.0...v4.0.0 before it lands in any roadmap commitment. Until that diff is reviewed, do not assume new capabilities or absence of breaking changes — the release notes published for v4.0.0 are only a compare link.
• Use cases worth validating before committing product scope: API payload normalization at the boundary, audit/diffing of stored JSON, and per-tenant configuration merging. Each is a candidate for a spike rather than a shipped commitment.

When to Consider This Package

Adopt when:

• The application is a Laravel/PHP service already persisting data in JSON/json columns or casting to array/collection.
• Product requirements include nested reads and writes with dot notation, merging defaults into stored payloads, or returning a consistent shape to an API consumer.
• Multiple teams touch the same JSON-shaped domain object and would benefit from one supported accessor rather than divergent helpers.
• You want the behavior to be unit-testable in isolation without hitting the database.
• Engineering has capacity for a one-time major-version migration review (mandatory here, given v4.0.0).

Look elsewhere when:

• You need querying inside the document (filtering, sorting, aggregation over nested keys). That is a database concern — Postgres jsonb operators, MySQL JSON functions, or a document store — not a PHP wrapper.
• You need schema enforcement at write time. A PHP accessor does not replace JSON Schema validation, database constraints, or a typed DTO layer.
• The data model is genuinely relational and JSON is being used to avoid migrations. Adding an accessor library entrenches a modeling decision you may want to reverse.
• The stack isn't Laravel, or you're on a PHP/Laravel version outside the package's supported matrix — verify the composer.json constraints for v4.0.0 explicitly, since major bumps commonly raise the minimum PHP/Laravel floor.
• Native data_get/data_set plus Eloquent casts already cover the need. The package's value is ergonomics and consistency at scale; a single call site does not justify a dependency.

Gate before any adoption: obtain the actual v3→v4 diff, confirm breaking changes against your call sites, check for deprecations and removals, and pin the version in composer.json rather than floating to ^4.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost dependency that standardizes how we handle the JSON-shaped data already in our product — settings, preferences, integration payloads. The business case is reduced custom code and faster iteration on features that touch those payloads, not new user-facing capability. The v4.0.0 release is a major version, which means the upgrade carries a bounded engineering cost; we should fund a short review before adopting, and we should not attach a delivery date to any feature that depends on it until that review is done.

To engineering: The package gives a fluent, Laravel-idiomatic object for JSON documents — dot-notation access, safe nested writes, merge semantics — replacing hand-rolled data_get/data_set chains and per-feature casts. It is a convenience layer, not a validation or query layer: it does not enforce schema and does not help you filter inside a JSON column. The immediate action item is the v4.0.0 breaking-change review — diff against v3.0.0, confirm the PHP/Laravel support matrix, identify removed or renamed methods, and inventory our call sites. Recommend pinning the version and covering the integration with a thin internal adapter so a future major bump is a single-file change rather than a codebase-wide sweep.

Recommendation: Proceed to evaluation spike; defer adoption decision and any roadmap commitment until the v4.0.0 diff has been reviewed and our call-site inventory is complete.