Qbjs Parser Laravel Package

Technical Evaluation

What it is. A narrow transformation library: take the JSON rule tree emitted by jQuery QueryBuilder (the {condition, rules:[...]} structure), and turn it into database query predicates. It sits on a single seam — untrusted client JSON in, query builder out.

Architecture fit. Good, precisely because it is small. No migrations, no schema, no background workers, no external services, no state. It is a leaf dependency whose blast radius is one feature (ad-hoc filtering / reporting). The input contract is public, versioned, and stable — jQuery QueryBuilder's rule JSON has not meaningfully changed in years — so the package is not defending a moving target. Fit within Laravel is natural if it emits an Illuminate\Database\Query\Builder or Eloquent builder that we can still constrain with tenant scopes, soft deletes, and global scopes. Fit degrades if it hands back raw SQL strings, because we then lose the ability to compose and re-constrain.

Integration feasibility. Moderate effort, low technical uncertainty. The parsing itself is a solved problem; the real work is the policy layer around it (see below). Verify from composer.json before committing: PHP constraint, Illuminate/Laravel version support, whether it is framework-agnostic or coupled to Illuminate contracts, and whether a test suite exists that we can run as a conformance check.

Technical risk. High, but concentrated and mitigable.

• Adoption signal: effectively zero. 0 stars, 0 dependents, single publisher, one release (2024-03-22). There is no evidence of production use anywhere. Treat as unreviewed third-party code, not as an established library.
• Security surface. The package's entire purpose is converting attacker-controllable JSON into a database query. If it concatenates identifiers or forwards operator strings verbatim, it is an injection vector. Even if it parameterizes values correctly, it almost certainly does not enforce a column allowlist or operator allowlist — that must be ours, upstream of the parser.
• Silent incorrectness is the dominant risk. A filter UI that quietly drops an unsupported rule and returns a broader result set is worse than one that 500s, because users will export and act on the data.
• Robustness. Deeply nested groups and large rule sets are recursion and query-size hazards; verify limits exist.
• Abandonment. Assume it. Mitigation is that the code is small and the spec is public — a fork or clean-room rewrite is days, not months.

Key questions for the spike. Bound parameters or string interpolation? Does it fail closed on unknown operators, or silently skip? Nested groups and NOT supported? Empty rule set behavior? Does the output expose id/field mapping we can validate against our allowlist? Return type — builder or string? Declared PHP/Laravel matrix? Existing test coverage?

Recommendation. Timeboxed spike yes; permanent dependency no. Vendor or fork from day one so we are not patching code we do not own.

Integration Approach

Stack fit. Clean if the application is Laravel 10/11 + Eloquent and the frontend already uses jQuery QueryBuilder. If the parser is Illuminate-coupled, it is not reusable in non-Laravel services — acceptable for an admin/reporting surface, a constraint if filtering ever needs to run in a separate reporting service or a queue worker.

Migration path. Do not call the package from controllers or form requests. Introduce one interface — RuleSetCompiler::compile(array $rules, FilterPolicy $policy): Builder — and make the package the first implementation behind it. Keep a second implementation (hand-written) in reserve. Swapping vendors later becomes a container binding change with no call-site churn, and it forces the policy object into the signature where it belongs.

Compatibility. Pin an exact version. Encode the tested PHP/Laravel matrix in CI. Add conflict entries for untested Illuminate majors so upgrades fail loudly at composer update rather than quietly at runtime.

Sequencing.

1. Spike (1–2 days). Branch, install, feed 20 real rule sets captured from the product, inspect the generated SQL by hand. Include hostile inputs: unknown operator, column not in schema, 50-deep nesting, empty rules, IN with 10k values.
2. Policy layer first, before wiring it up. Per-resource column allowlist, per-column operator allowlist, max nesting depth, max rule count, max IN cardinality. Reject with a 422; never ignore.
3. Golden-fixture tests. JSON → expected SQL / expected result set, committed as test data. This is also the artifact that makes an eventual rewrite safe.
4. Wrap behind the interface, feature-flag to internal users, shadow-compare compiled results against a manual filter for a week.
5. Decide fork vs. vendor at the end of the spike — not later. If the answer is fork, fork immediately so subsequent fixes land in our repo.

Operational Impact

Maintenance. Budget for ownership. No upstream patch stream, no release cadence to plan around; the next Laravel major will break this and it will be our ticket. The fork is small — likely a handful of classes — but it must be scheduled, not discovered.

Support. None. No issue triage, no security advisories, no maintainer response path. We become the incident response team for this code path. That is tolerable only because it is a leaf feature that can be disabled by flag without taking down checkout, auth, or data ingest.

Scaling. Parse cost is noise next to query execution. The scaling risk is query shape: unbounded IN lists, wide OR trees, and unindexed column combinations. Enforce server-side caps and a statement timeout; log any rule set that trips a cap, since those are the ones that will page someone. If compiled queries are cached, the cache key must include the rule JSON hash and the policy version — otherwise tightening the allowlist silently does not take effect for cached entries.

Failure modes, ranked by damage.

1. Silent over-broad results — a rule dropped or mis-mapped returns a superset; users export and act on wrong data. Mitigate by failing closed, logging every rejected rule, and rendering the compiled filter description back to the user as a confirmation.
2. Unsupported operator/column reaching the database — error or wrong data; same mitigation.
3. Deep nesting or oversized rule sets — timeouts, PHP-FPM worker exhaustion, one user degrading the surface for everyone.
4. Injection via identifier or operator string — contained to the reporting surface but still a data-exfiltration path.
5. Upgrade blockage — the dependency pins us out of a Laravel major at an inconvenient time.

Ramp-up. Low for the library itself; half a day for an engineer comfortable with query builders to read the parser end-to-end. The real ramp-up is the guardrails — allowlists, caps, fixtures, error semantics — which the package does not provide and which will be the majority of the work. Plan the estimate accordingly: the library saves roughly a day of parsing code and costs a day of review plus an ongoing fork obligation. Worth it only if the spike confirms the policy layer can sit cleanly outside the package rather than requiring patches inside it.