Rql Parser Laravel Package

Product Decisions This Supports

• API query-surface design (build vs. buy vs. borrow). Decides whether we expose a filter/sort/pagination DSL to API consumers and whether we hand-roll a parser, adopt an existing grammar, or constrain clients to fixed query parameters. This package is a parser only — it converts an RQL string into a query AST; it does not touch your database, ORM, or authorization layer.
• Public API contract and GA gate. If we publish RQL as part of our API contract, filtering semantics become a versioned public interface. That is a product commitment with a long tail (docs, client SDKs, deprecation policy), not an implementation detail to be swapped later.
• Pagination contract correctness. The v3.0.1 fix guarantees LimitNode always carries an integer offset. Offset/limit typing is client-visible: a string/null/float offset that leaks into our translator produces off-by-one pages, empty result pages, or 500s at the API edge. This is a concrete reminder that the pagination half of the grammar is as much a contract as the filter half, and that we must type-normalize at the parser boundary, not downstream.
• Roadmap items it could unblock: saved/shared filters, ad-hoc reporting and exports, admin console search, partner integrations, and any feature where the customer composes the query rather than picking from our predefined facets.
• Partner/integration fit. Relevant when an external counterparty (or parent platform) already speaks RQL — in which case the language is a given and we're only choosing the implementation.
• Complexity budget for the query layer. Adopting an AST-based approach is a decision to own a compiler: AST → Eloquent/Doctrine/SQL/Elasticsearch, plus validation, allow-listing, and injection defenses. That is ongoing engineering cost a PM should size before committing — and it does not shrink because upstream is alive.
• Informs the "no custom DSL" default. Even if we don't adopt it, evaluating it makes the case for simpler alternatives (typed filter params, Laravel query scopes, Spatie Query Builder) concrete and defensible for the roadmap.
• Explicit non-decision: this is not a product differentiator. Customers buy outcomes, not grammar. Treat any adoption as an internal engineering choice with a maintenance line item, not a roadmap feature.

When to Consider This Package

Note on the change: the prior assessment treated this package as abandoned (last release 2019, archived). The v3.0.1 patch release invalidates that premise — there is an active v3 line under maintenance. That removes our single biggest objection, but a patch release is one data point, not a maintenance guarantee. Verify release cadence, supported PHP versions in composer.json, PHPUnit/CI status, and whether issues are being triaged before treating it as a safe runtime dependency.

Consider it when:

• A contract, partner, or existing platform integration already specifies RQL. Then the grammar is fixed and the only question is whether to write the parser ourselves — and a maintained implementation is now a credible answer.
• You are on a modern PHP 8.x / current Laravel stack and v3 is validated against it. Confirm this from the package metadata rather than assuming from the version number.
• You want an AST-based parser you don't have to write and are prepared to own the downstream half: the AST → ORM translator, per-endpoint field allow-lists, operator restrictions, and injection defenses. Those remain entirely ours.
• Your pagination needs fit the grammar's limit/offset model and you can normalize and clamp values after parsing (the v3.0.1 fix helps, but bounds-checking max page size is still our job).

Look elsewhere when:

• Release cadence and security-response posture can't be confirmed. A single patch is not a track record; if you need a documented CVE path, require evidence before adopting.
• Your filtering needs are simple and known — typed query params plus Laravel query scopes or Spatie Query Builder will ship faster and be easier to secure.
• You need full-text search, relevance ranking, or complex boolean pushdown to a search engine — RQL is a filter language, not a search language.
• Your consumers expect OData, JSON:API, or GraphQL conventions rather than RQL. Choosing a niche grammar shifts the learning cost onto every API consumer.
• Ecosystem breadth still matters to you. Even maintained, a small package means few third-party bug reports and no community to inherit maintenance from if the maintainer steps away.

Practical path: adopt it behind an internal interface — parse to AST, validate against a per-endpoint field allow-list, normalize limit/offset (ints, clamped to a max page size), then compile in our own translator. That keeps the grammar swappable without an API break and confines the dependency to the parse step.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, single-purpose library that parses a standardized query syntax (RQL) into a structured form our code can act on. It is not a complete filtering solution — it does no database work, no authorization, and no validation of what a user is allowed to see. The risk picture has improved since our last review: the project was previously dormant and is now actively maintained, with a v3.0.1 bugfix correcting how pagination offsets are typed. That was our main blocker, and it is gone — but one patch is not a track record, so the remaining question is maturity and support guarantees, not abandonment. Ownership of the query translator, allow-lists, and security review still sits with us.

Recommendation: move from "do not adopt" to "pilot behind an internal interface." Adopt v3 as the parse step only if a short spike confirms current PHP/Laravel support, CI health, and a plausible release cadence. Budget the fork fallback, the field allow-list layer, and the AST → ORM translator as one line item with a named owner. If RQL is externally mandated by a partner contract, this release makes adoption cheaper than forking; if it is not mandated, keep the simpler maintained filtering approach as the default and revisit only when a customer commitment demands it.

To engineering: the appeal is unchanged — small, focused, AST-based, which is the right shape: parse once, validate against a per-endpoint allow-list, compile to your persistence layer. v3.0.1 fixes LimitNode to always expose an integer offset, so you no longer have to defensively coerce that field, though you should still clamp page size and validate bounds. The compiler, authorization rules, and security review remain yours. Keep the grammar behind our own interface so we can replace the parser without breaking the API contract, and pin the version until you've confirmed the maintenance cadence.