Jsonpath Laravel Package

Product Decisions This Supports

• Build vs. buy on JSON querying: 2.2.0 completes the shift from "path lookup helper" to a standards-conformant query engine. The opt-in JSONPath::RFC9535 mode delivers full RFC 9535 query parsing — unions across mixed selector types, filters, slices, Unicode and escaped member names — with eager type validation. The case for hand-rolling a bespoke traversal/filter layer, or buying an external query service, is now weak on both capability and provability (715 pinned compliance cases).
• Migration and rollout strategy: The new behavior is opt-in; existing calls keep prior semantics. That decouples "adopt the standard" from "upgrade the dependency," so we can schedule a version bump as routine maintenance and treat RFC-mode enablement as a separate, testable product decision per surface.
• Feature scope for search/filter UX: I-Regexp matching plus full RFC filter and slice semantics makes user-authored filters, saved searches, rule builders, and alerting conditions a realistic in-house feature. findPaths() adds normalized result paths with ordered duplicate matches, which unlocks "show me where this value came from" affordances — match highlighting, provenance panels, audit trails, and diff/compare views — that were previously bespoke work.
• Roadmap sequencing: The parser and type checker validate function expressions without evaluating user-controlled PHP, and invalid queries are rejected independently of document contents. Security review scope narrows to input validation, so end-user-expression features can be scheduled earlier than a custom-engine path would allow.
• Quality and maintainability signals: Integration of the full pinned compliance suite (asserting values and normalized paths together), retained compatibility tests, explicit mode-isolation regression coverage, and CI-enforced 100% coverage are procurement-grade evidence. These reduce the diligence burden versus an internal engine whose correctness we would have to argue from our own test suite.
• Risk posture / compliance inputs: Standards-conformant, mode-isolated behavior with eager validation and PCRE resource limits are citable controls for security questionnaires and design reviews. Supports keeping data-transformation logic in-application rather than in an external service that carries its own data-handling review.
• Use cases unlocked or de-risked: Third-party API response normalization, dynamic configuration and feature-flag parsing, webhook payload routing, validation and enrichment pipelines, tenant-defined rules, and now result-provenance/audit surfaces — all with one narrow dependency instead of per-integration custom code.

When to Consider This Package

Adopt when most of the following hold:

• You routinely transform or extract from JSON of non-trivial shape, and custom traversal code is accumulating across features.
• You need standards-based semantics (RFC 9535 / RFC 9485) for portability, interoperability, or a documented behavior contract — and you value conformance evidence (pinned compliance suite) over vendor claims.
• End users, tenants, or config authors will supply paths or expressions, and you need typed validation and bounded regex execution rather than trusting raw input.
• You want result provenance (findPaths() normalized paths) as a first-class capability rather than a bolt-on.
• You want a narrow, single-purpose dependency over a full query/transformation service or a DSL you would have to own.

Look elsewhere when:

• Your needs are shallow (a handful of fixed keys per payload) — native array access is cheaper than a dependency and its upgrade cadence.
• You require an execution sandbox with hard CPU/memory isolation, distributed querying, or streaming over datasets too large to hold in memory; PCRE limits help but are not a general resource governor.
• You need a full transformation language (joins, aggregation, schema mapping) beyond path selection and function evaluation.
• Your platform is pinned below the package's supported PHP/Laravel versions, or your team cannot commit to tracking RFC-driven behavior changes.
• You cannot absorb dual-mode complexity: two coexisting semantics mean every surface must be explicit about which mode it uses. Teams without the discipline to standardize on RFC mode and test mode isolation should treat this as a maintenance tax rather than a benefit.
• Governance forbids adding dependencies for logic already adequately covered in-house.

How to Pitch It (Stakeholders)

For executives: This release makes the library a conformance-tested, standards-based JSON query engine, and it ships as an opt-in mode so upgrading carries no behavioral risk. It lets us ship user-configurable filtering, data mapping, and "where did this value come from" provenance features faster, with fewer custom components to maintain. The 715-case compliance suite and enforced full coverage give us defensible answers in security and compliance reviews: bad expressions are rejected up front, regex execution is bounded, and we are not running arbitrary user-supplied PHP.

For engineering: Version 2.2.0 adds opt-in JSONPath::RFC9535 mode — complete standard query parsing (unions with mixed selector types, filters, slices, Unicode and escaped member names) with eager type validation — while existing calls keep current behavior. findPaths() returns normalized RFC result paths, including ordered duplicate matches, which enables provenance and match-highlighting features. All 715 pinned compliance-suite cases run in CI against values and normalized paths together, alongside the original compatibility tests and new mode-isolation, nested-absolute-query, and JSON value-comparison regressions; CI now enforces 100% coverage and PHP CS Fixer is the sole style tool. Recommended next steps: pin 2.2.0, pick one or two candidate surfaces and explicitly opt them into RFC mode behind a flag, add regression tests for expression and regex edge cases (Unicode, anchors, empty matches) in the surfaces we expose to users, confirm the security review narrows to input validation, and audit hand-written JSON traversal code as consolidation candidates — including any ad-hoc "which path matched" logic that findPaths() can replace.