Query Builder Parser Laravel Package

Product Decisions This Supports

Build vs. buy for the filtering feature. This package collapses the "advanced filter" feature from a quarter-scale build into a spike-scale integration: one class, one method (parse($rulesJson, $builder)), one allow-list array. The buy-side cost is a composer dependency; the build-side cost is a rule-tree-to-SQL compiler plus the operator semantics (LIKE, begins/ends, between, null checks, nested AND/OR) that this package already ships and has bug-fixed over many releases. That is the core decision it informs.

Roadmap sequencing — ship filtering without touching the data model. Because the parser returns an Illuminate\Database\Query\Builder you continue chaining, it inserts at the HTTP→builder seam with no migrations, no model changes, no new persistence. That lets a filter feature land in a release cycle alongside other work rather than as its own epic.

Which surfaces get filtering first. The package supports a clear scoping decision: read-only list, search, filter, and export endpoints implemented as DB::table(...)->get(). It is a poor fit for write paths, and it is out of scope for multi-tenant endpoints where a dropped predicate means cross-tenant leakage — that needs a purpose-built query layer, not a parser.

Use cases it unlocks, ranked by fit: internal admin/back-office grids, reporting and CSV export filters, DataTables-backed list views (documented end-to-end, including the client-side fnServerParams pattern), and saved-filter UX for power users.

The allow-list as a product contract. "Which columns are filterable" becomes a named, reviewable artifact owned by a person, and schema changes create an explicit allow-list review step. That is a governance decision the PM should make up front, not inherit by default.

Depth-of-filtering decision. JoinSupportingQueryBuilderParser covers correlated exists / not exists subquery filtering through a declared join map. That is enough for many multi-table filter needs, but it is a decision to make explicitly: if the roadmap wants filtering across Eloquent relationships (whereHas) or against computed/aggregated values, this package does not shorten that path and should not be sold as if it does.

MongoDB is a separate decision, not a free option. The Mongo path depends on jenssegers/mongodb, which has been superseded by mongodb/laravel-mongodb. Treat it as its own evaluation with its own cost.

Frontend dependency posture. The client half is jQuery QueryBuilder. The JSON contract is portable, but adopting the documented integration means committing to maintain that component. If jQuery is declining in your frontend, that is a real, separable cost.

Maintenance budget signal. Releases track framework majors — 1.6.3 for Laravel 10, 2.1.0 for 11, 2.2.0 for 12 and 13 — which supports a low-but-nonzero dependency maintenance line rather than a "we'll fork it eventually" line.

When to Consider This Package

Adopt when all of the following hold:

• Stack is Laravel 9–13 on Illuminate Database, and candidate endpoints are already written as controller → DB::table(...)->get().
• The filterable field set is small, stable, and has a named owner who can approve allow-list additions.
• Endpoints are strictly read-only — list, search, filter, export. No write path flows through the parsed query.
• The UI wants a visual rule builder with nested AND/OR groups and standard operators, and the frontend team will maintain a jQuery QueryBuilder component.
• A one-day spike to validate is more valuable right now than a quarter of design work.

Adopt with an explicitly estimated hardening wrapper, treated as first-class scope, not integration friction: rule-tree depth and node-count caps, per-field operator allow-listing, in-list length limits, value type coercion, statement timeouts at the connection level, error translation to user-facing messages, and audit logging of who filtered on what. The package's entire safety guarantee is the column allow-list; everything else is yours.

Look elsewhere when:

• Filtering requires Eloquent relationships, global scopes, soft-delete semantics, or computed/aggregate columns.
• Any candidate endpoint touches multi-tenant data where a missing predicate leaks rows.
• MongoDB is the primary need — evaluate mongodb/laravel-mongodb directly rather than through this adapter.
• There is no appetite for DoS hardening in front of the primary datastore, or a single-maintainer dependency in front of it is unacceptable without a fork-and-own contingency (160 stars, zero dependents, one maintainer who dogfoods it).
• The frontend is a modern SPA with no jQuery presence and no willingness to reintroduce it; you would be rebuilding the client anyway.
• Cross-engine semantic portability matters — LIKE, case sensitivity, and date handling differ per engine, and the package does not normalize them.

How to Pitch It (Stakeholders)

For executives: This is a small, MIT-licensed adapter that turns the output of a visual filter widget into safe, parameterized Laravel queries. It buys us an advanced-filtering capability in days rather than a quarter, and it is actively kept current with Laravel 12 and 13. The trade is that it is a small open-source project with a single maintainer sitting in front of our database, so we budget for two things alongside it: a thin hardening layer (query complexity caps, statement timeouts, filter audit logging) and ownership of the column allow-list as a security control. The alternative — building and maintaining our own rule-to-SQL compiler — is more expensive and buys nothing the customer can see.

For engineering: One class, one method. Construct with an allow-list of columns; call parse($rulesJson, DB::table('...')); you get back the builder you already use and keep chaining before get(). No models, no migrations, no connection handling, no new persistence. Architecturally it is a compiler at the request→builder seam. It compiles nested AND/OR rule trees into WHERE/LIKE predicates, has a join-aware variant built on correlated exists subqueries, and has documented DataTables integration including the client serialization pattern. It does not give us complexity guardrails, operator restriction, type coercion, or scoping — we own those, and we should size them before committing to a customer-facing date.

What we are explicitly not buying: query-cost protection, cross-engine semantic parity, Eloquent relationship traversal, or institutional support for the dependency. If any of those are must-haves, the decision changes and we should say so now rather than after the spike.