Jsonq Laravel Package

Technical Evaluation

What it is: nahid/jsonq is a framework-agnostic PHP library that loads a JSON document (file, string, or URL) into memory and exposes a fluent, SQL-flavored API — where, orWhere, whereIn, sortBy, groupBy, sum, avg, first, paginate — over the decoded structure. It is a read-only query layer, not a persistence engine, not a schema validator, and not a streaming processor.

Architecture fit. The package is a leaf dependency: no service provider required, no config to publish, no database, queue, or HTTP coupling. That is architecturally clean — it can be dropped into a controller, a console command, or a domain service without infecting the rest of the codebase. The tension is that it encourages a pattern (loading a whole document, chaining queries inline) that is easy to write and hard to test at scale. Treat it as an anti-corruption layer candidate, not a core primitive.

Integration feasibility. Composer-installable with a permissive CC0-1.0 license, so there is essentially zero legal friction to adoption, forking, or vendoring. The real friction is version currency: last tagged release is February 2021, which predates PHP 8.1/8.2/8.3 hardening. Expect to verify:

• Declared php constraint in composer.json versus your runtime (PHP 8.2+ deprecations around dynamic properties, strlen(null), implicit float-to-int casts).
• PHPUnit and dependency versions — whether the suite even runs on a modern CI image.
• Whether a Laravel facade/service provider exists in-tree or only via a third-party wrapper.

Technical risk. Ranked:

Key questions to answer before committing:

1. Does the package evaluate conditions via eval() or dynamic function invocation anywhere? If yes, hard stop for any path touching user-supplied operator input.
2. What is the largest realistic document size, and what is the p95 request memory ceiling? (Anything above ~10–20 MB per request is a design smell for this library.)
3. Do we need write-back, partial updates, or concurrent mutation? The library does none of these.
4. Is there a first-party service provider, or are we hand-wiring? Determines whether Laravel developers get facades and config or a new JsonQ(...) in every class.
5. Who owns the fork if a PHP 8.4 incompatibility lands in six months?
6. Is a narrower, better-supported alternative sufficient — jmespath.php for path extraction, justinwalsh/query-style array helpers, or Laravel's native Arr::/data_get() for the 80% case?

Assessment: technically viable for bounded, read-only querying of small-to-medium JSON fixtures, config blobs, or third-party API payloads. It is not viable as foundational infrastructure without a fork-and-own commitment.

Integration Approach

Stack fit. Strong for Laravel 9–11 on PHP 8.1–8.3 provided a compatibility spike passes. It is framework-neutral, so it also fits Symfony or plain PHP, which is an advantage for shared internal packages. It does not integrate with Eloquent, so do not let it become a shadow ORM — the moment a query is doing relational work or paginating a large dataset, that data belongs in a database.

Migration path. Do not call the library directly from controllers or jobs. Introduce a thin internal adapter:

• JsonDocumentRepository interface with methods expressed in your domain vocabulary (findActiveAccounts(), summarizeByRegion()), not where()->orWhere().
• One adapter implementation backed by jsonq, one backed by jmespath.php or plain array filtering, selectable by config.
• Contract tests written against the interface, so the underlying engine is swappable and the semantics are pinned down by your tests rather than by the library's README.

That adapter costs roughly one to two days and converts an unmaintained dependency from an architectural risk into a replaceable detail.

Compatibility. Pin an exact version with a caret floor and a hard ceiling in composer.json. Run the library's own test suite inside your CI image on your target PHP matrix — treat a green run as the compatibility gate, not Packagist metadata. Enable composer audit (it will likely report nothing, which is itself informative), and suppress third-party deprecations via PHPUnit's deprecation handler rather than by downgrading PHP.

Sequencing.

1. Spike (1–2 days): install, run the upstream suite on target PHP, load a representative production-shaped document, measure peak memory and p95 latency.
2. Semantics capture (2–3 days): write conformance tests for type coercion, missing keys, empty results, malformed input, deep nesting. Publish the results as internal docs.
3. Adapter + behind-flag wiring (3–5 days): implement the interface, route one non-critical read path through it behind a feature flag.
4. Shadow comparison: run jsonq results against the current implementation or a jq/JMESPath baseline on real payloads; diff outputs for a week.
5. Broaden to additional read-only paths only after the diff stays clean.
6. Fork (nahid/jsonq under the org, CC0 permits this with no attribution obligation) the moment a patch is needed; publish to a private VCS repo and track upstream diffs manually.

Operational Impact

Maintenance. This is the dominant cost. With no release since 2021, the library is effectively yours the day it lands in production. Budget: ~1–2 engineer-days per year for PHP-version upkeep and dependency bumps, plus unbounded time if a data-shape bug surfaces in a hot path. CC0-1.0 makes the licensing side frictionless — no attribution, no copyleft contamination, no redistribution constraints — but note it is a public-domain dedication rather than an OSI-approved software license and carries no express patent grant. For a JSON query helper that is a negligible risk; it would not be for anything cryptography-adjacent.

Support. Community-only. GitHub issues with no SLA, no security disclosure policy, no LTS branch. Escalation path is "read the source." Your team must be comfortable debugging the library itself — the codebase is small enough that this is realistic, but it should be an explicit, named-owner assumption rather than an unspoken hope.

Scaling. Constrain this deliberately:

• Document size: comfortable under a few MB; degrade gracefully toward 20 MB; refuse above that. Decoded-array overhead means a 10 MB file can easily consume 60–100 MB of PHP memory, and memory_limit exhaustion is a fatal, uncatchable failure in many configurations.
• Request volume: the library is pure CPU and memory per invocation. There is no cache, no index, no lazy evaluation. At high QPS on the same document, you will want an application-level cache of the result, not the parsed document, or you will rebuild the decode on every call.
• Concurrency: read-only, so no locking concerns. Multiple processes each hold their own copy — memory scales linearly with worker count, which matters under PHP-FPM.
• Outgrowing it: the moment you need streaming, partial extraction from large files, or repeated queries against one corpus, move to a database (SQLite/JSON1, Postgres jsonb), a streaming parser, or jq as a subprocess. The adapter boundary makes that a contained change.

Failure modes to instrument. Malformed or truncated JSON (upstream API changes are the usual cause) — should raise a typed domain exception, not a raw library exception. Missing-key behavior drifting between "null" and "throws" across query shapes. Silent type coercion producing subtly wrong sums and filters — this is the dangerous one, because it fails open and looks plausible. Memory exhaustion on an unexpectedly large payload. Deprecation notices promoted to exceptions by a strict error handler after a PHP upgrade.

Ramp-up. Very low for developers: the API reads like SQL, and a mid-level Laravel engineer is productive within an hour from the README. Documentation is README-grade, not reference-grade, so the effective onboarding cost is not learning the API but learning its undocumented edge behavior — which is precisely what the conformance tests from the integration phase should absorb. Do not let individual developers rediscover those semantics in production.

Recommendation. Adopt for narrow, read-only, small-document querying behind an internal adapter, with an explicit named owner and a documented fork plan. Do not adopt as shared platform infrastructure, do not expose it to user-controlled operator input, and do not use it where a database or a streaming parser is the honest answer. The 870 stars and public-domain license make it a low-friction experiment; the 2021 release date makes it a poor long-term bet without ownership.