Rql Parser Laravel Package

Technical Evaluation

Architecture fit. graviton/rql-parser remains a spec-style parser for Resource Query Language — the ?filter=, ?sort=, ?limit=, ?select= URL grammar — converting a query string into an AST of query objects. That parsing concern is still a clean, isolated responsibility and still only ~30% of the problem: the package stops at the AST, and the Eloquent translation, field whitelisting, and authorization layers remain ours to build and own. Nothing in v3.0.1 changes that division of labor. Two things do change the fit analysis:

• Version 3.x. A v3.0.1 release implies a 3.0.0 predecessor and therefore a major-version line that postdates the previously assumed 2019 codebase. A major bump is a signal of breaking API/AST changes, so the AST shape, node classes, and constructor signatures must be re-inspected rather than assumed.
• LimitNode integer offset. The patch forces LimitNode to always carry an integer offset. That is a type-coercion bug in the limit/pagination path, which is exactly the class of defect the prior assessment flagged as a PHP 8.x risk. It also means that before this patch, a non-integer offset could reach downstream consumers — a correctness and potentially a query-construction hazard for anything that interpolates LIMIT/OFFSET.

Integration feasibility. Unchanged and still favorable: Composer-installable, framework-agnostic, no Slim or Graviton dragged into the dependency graph. The parser layer remains cheaply unit-testable. The Eloquent adapter and policy layer remain bespoke in every scenario, so the package's value proposition is still narrow — a maintained parser plus a typed LimitNode is a modest improvement, not a strategic one. One feasibility note: because this is a 3.x line, any prior spike, prototype, or internal snippet written against an earlier major must be re-baselined before it can be trusted as an effort estimate.

Technical risk. Still high, but the risk profile has shifted rather than shrunk:

• Lifecycle status is now ambiguous, not confirmed-abandoned. The prior assessment asserted "archived, last release 2019-07-15." A v3.0.1 publication contradicts a strict reading of that. However, a single patch release is not evidence of sustained maintenance: it may be a one-off fix, a maintainer un-archiving briefly, or a republished fork. Treat as unverified until commit cadence, changelog continuity, and the publishing maintainer are confirmed. The supporting data set for the previous assessment was empty, so the lifecycle claims were never empirically grounded; this release is the first hard datum and it points both ways.
• PHP compatibility partially de-risked, not resolved. The offset coercion fix removes one plausible PHP 8.x failure mode. It does not establish that the rest of the parser runs cleanly on the target PHP version; deprecations elsewhere, null handling, and return-type mismatches still require a CI matrix.
• Major-version migration exposure. If we pilot on 3.0.1, we inherit whatever 3.0.0 changed. If we later need to move to a hypothetical 4.x, we absorb another breaking change from a vendor whose release cadence we cannot forecast.
• Zero or near-zero dependents. Still no meaningful ecosystem validation; we remain among the first production users.
• Doctrine-oriented output. Unchanged — possible translation overhead for Eloquent.
• Security surface. Unchanged and still the largest risk. The parser performs no authorization or field-level security; without a strict whitelist it is an injection and data-exposure vector. Note that the offset bug sat adjacent to this surface: an unbounded or malformed offset is a resource-exhaustion vector, and pre-patch behavior permitted a non-integer offset to propagate. The patch narrows that specific hole; the whitelist requirement is untouched.

Key questions.

• What shipped in 3.0.0, and is the 3.x line a genuine upstream continuation, a re-activation, or a fork? Who publishes these releases, and is the repository still archived?
• What is the actual release history between 2019 and now, and what is the current commit cadence? A single patch does not constitute a maintenance commitment.
• Does v3.0.1 run cleanly on our target PHP versions, or did the offset fix merely mask one of several coercion issues?
• Is the 3.x AST shape and public API compatible with what our spike/estimates assumed, or does the major bump invalidate prior effort sizing?
• What are LimitNode's guarantees post-patch — does it clamp, reject, or accept negative and oversized offsets? Integer-ness is not the same as bounds-safety.
• Do we actually need RQL-spec compliance, or would Laravel-native conventions (?filter[field]=value, Spatie Query Builder) satisfy requirements with less risk?
• Is the AST persistence-agnostic, or does it carry Doctrine-specific structures we must unwrap?
• What is the license, and does it permit a maintained vendor fork?
• Who owns the field/operator whitelist and the authorization model, and is that policy expressible outside the parser?
• Are there existing internal RQL consumers whose semantics we must match?

Integration Approach

Stack fit. Unchanged and asymmetric. Parser drops into a Laravel service layer; execution must be built for Eloquent. No service provider, facade, config publish, or HTTP integration — we add a singleton binding, a Request-to-AST pipeline, and a query-building service. Net fit remains "parsing library we wrap," not "Laravel package we install." The offset fix makes that wrapped surface slightly more predictable, which is welcome but not structural.

Migration path. Still introduce RQL behind a versioned endpoint or feature flag, never by mutating existing query-parameter contracts. Run RQL and legacy parameters in parallel during a deprecation window with per-client usage telemetry. Because we would be adopting a fresh major line, prefer a greenfield endpoint over retrofitting an existing one — that keeps the 3.x blast radius contained and gives a clean rollback lever.

Compatibility. Pin exactly 3.0.1; do not use caret or tilde constraints, and do not assume 3.0.x will receive further patches. Add explicit PHP version constraints and a CI matrix over the target production PHP. Establish and record a baseline AST snapshot for a representative query corpus against 3.0.1 specifically, so future upgrades can be diffed rather than re-derived. Plan for a vendored fork as before, and vendor the code rather than depending on a remote, so reproducibility does not hinge on an ambiguous upstream. Keep the fork shallow and track divergence explicitly, including the offset patch.

Sequencing.

1. Lifecycle recon (0.5 day, do this first): confirm whether upstream is active, archived, or forked; obtain the changelog for 3.0.0 and 3.0.1; identify the maintainer. This determines whether everything below is an adoption or a fork-adoption.
2. Spike (1–2 days): install pinned 3.0.1, verify PHP compatibility, parse a representative corpus, capture the AST snapshot, and specifically probe LimitNode behavior — integer, numeric-string, null, negative, zero, and oversized offsets — plus the same edge cases on sort and filter nodes.
3. Adapter design: define the field/operator whitelist, the AST-to-Eloquent translator contract, and error semantics (400 vs. 403 for disallowed fields; reject vs. clamp for out-of-range limits).
4. Build + contract tests: golden-file parse tests, SQL assertions for translation, and security tests for injection, select-based field exposure, and offset/limit abuse. Add a regression test pinning the integer-offset invariant so a future upgrade that regresses it fails CI.
5. Security review: injection, mass assignment via select, resource exhaustion via unbounded limit/offset.
6. Pilot: feature-flagged exposure on one internal, low-risk resource; measure parse failures, query latencies, and rejected-query rates.
7. Expand and decide: widen only after thresholds are met; at that point formally decide fork-and-maintain versus replace with a homegrown parser or a maintained alternative.

Operational Impact

Maintenance. Still the dominant cost, but the decision framing has moved from "orphaned, definitely ours" to "unknown, probably ours." A patch release could mean an engaged maintainer or a one-time drive-by fix; until that is established, assume we own the code. The codebase is small and the grammar is stable, so steady-state burden is modest — but it is a permanent line item and a single point of failure if the one engineer who understands the parser leaves. Budget a fork owner from day one regardless of what the lifecycle recon finds.

Support. No evidence of an upstream support channel, issue triage, or documentation refresh accompanying this release. The RQL spec is public, but this parser's interpretation may diverge from spec and from other implementations — and the LimitNode offset defect is a concrete example of the parser's observed behavior differing from what a naive consumer would assume. Internal documentation of observed edge cases is mandatory; the integer-offset invariant should be written down as a contract we now depend on, not just a test.

Scaling. Parsing remains CPU-bound string and AST work — negligible per request. The real scaling risks are unchanged: unbounded user queries (limit/offset abuse, expensive sort/filter combinations) and cache-keyed identical queries. Mitigate server-side with enforced maximum page sizes, a hard maximum offset, query complexity limits, and per-client rate limits. The patch makes LimitNode type-safe; it does not make it bounds-safe, so a deep-offset scan is still on us to block. Caching parse results for identical query strings is likely not worth the complexity.

Failure modes.

• Parse errors on malformed or adversarial input → must surface as clean 400s, not unhandled exceptions.
• Offset/limit coercion and bounds → a non-integer or extreme offset producing wrong pagination, SQL errors, or expensive scans. Reduced by 3.0.1, not eliminated; pinned by regression test.
• Major-version surprise on the next release → API or AST breakage; caught only by the AST snapshot diff and CI matrix.
• Runtime incompatibility after PHP upgrades → fatal errors or silent coercion bugs; caught only by the CI matrix.
• Authorization gaps → users filtering or selecting fields they should not see; still the highest-severity failure mode.
• Translator drift → RQL semantics and Eloquent behavior diverge (null handling, case sensitivity, in/eq edge cases), producing silently wrong result sets.
• Orphaned dependency → no upstream fix when a CVE lands; incident response entirely internal.

Ramp-up. A mid-level Laravel engineer learns the parser in 1–2 days. The real ramp-up is the adapter and the security model — 1–2 weeks to productive ownership, longer for the security-review competency needed to sign off on field/operator whitelisting. Add a small but real cost for lifecycle recon and for re-baselining against the 3.x AST. Name a designated owner before adoption; the ambiguous maintenance status makes "no one owns it" a worse option than it was before, not a better one.

Bottom line for a TPM. v3.0.1 is a small, sensible patch — a real type-safety fix in the pagination path — and it is the only hard evidence we have about this package's current life. It does not convert an abandoned dependency into a maintained one; at most it shifts the status to "unverified, possibly lightly maintained." Net position is unchanged: low-opportunity, low-strategic-value dependency that solves a narrow parsing problem and leaves the risky translation and security work to us. Spend half a day confirming whether 3.x is a live upstream or a fork before committing engineering time. Adopt only if RQL-spec compliance is a hard product requirement; otherwise evaluate maintained alternatives or a thin homegrown parser. In either case, pin the exact version, treat the fork as an owned internal component with a named maintainer, and pin the LimitNode integer-offset invariant in CI so this fix cannot silently regress.