Weave Code
Laravel Json Query Builder Laravel Package
asseco-voice/laravel-json-query-builder
Build complex Eloquent queries from JSON with asseco-voice/laravel-json-query-builder. Turn structured JSON payloads into safe, readable filters and sorts, making API-driven search and dynamic filtering simple in Laravel.
Building Eloquent queries from JSON
Frequently asked questions about Laravel Json Query Builder
- How do I install and use asseco-voice/laravel-json-query-builder in a Laravel app?
- Install it with Composer and publish the package config, then call the builder from a controller or a dedicated query-filter class, passing the decoded JSON payload. Setup is low ceremony, but the recommended pattern is to invoke the package behind your own QueryFilter interface so controllers never import the vendor namespace directly. That keeps the library as an implementation detail rather than part of your API contract.
- Does laravel-json-query-builder support Laravel 11, Laravel 12 and PHP 8.3?
- Do not assume it does. The last release was around March 2024, so Laravel 11, Laravel 12 and PHP 8.3+ support must be verified from the composer.json version constraints before you commit. Run a one-day spike against your exact Laravel and PHP version rather than trusting the README. If the package predates your Laravel major, budget for a fork-and-patch or exclude it from the project.
- How do I prevent users from filtering or sorting on sensitive columns like password_hash?
- User-supplied JSON reaching Eloquent is effectively mass assignment at the query layer, so you need a strict per-resource allowlist of filterable and sortable columns plus permitted operators. Confirm whether the package supports such allowlists natively; if it does not, enforce them in your own adapter before the payload ever reaches the builder. The package should never be your authorization layer, so apply policies and tenant checks first and reject anything not on the allowlist.
- Can I cap filter depth and filter count to avoid slow or expensive queries?
- Treat this as a hard requirement: unbounded filter counts, deep relation traversal and leading-wildcard LIKE patterns can generate very expensive SQL. There is no documented package-level guardrail, so add configurable limits for max depth, max filter count, allowed operators and max page size in your own wrapper. Validate the payload with a FormRequest or a JSON Schema before it reaches the builder, and reject oversized queries with a 422 rather than letting the database absorb the cost.
- How are Eloquent relations resolved, and can I scope them to the authenticated tenant?
- Check the source and the generated SQL to see whether relations become whereHas subqueries, joins or eager loads, because each behaves differently for performance and isolation. Whatever the mechanism, you must be able to constrain relation traversal to the authenticated tenant. Verify how the package interacts with global scopes, soft deletes and composite keys, since those are common leak points in filter libraries.
- Is it safe to expose this JSON query DSL as my public API contract?
- Generally no. If your API contracts are strict and versioned, exposing a third-party library's DSL as your public schema means swapping the library later becomes a breaking change for your clients. Introduce it behind an internal QueryFilter interface and pilot it on a single low-traffic read endpoint. Keep the JSON shape documented and owned by your application, not by the vendor package.
- How do I validate the JSON query payload, and does invalid input return 422 or 500?
- Validate shape independently with a FormRequest or JSON Schema validator before the payload reaches the builder, so malformed structures fail fast with a 422. Then confirm empirically whether the package rejects unknown fields or silently ignores them, and whether bad operators produce a validation error or a 500. Silent ignoring is the more dangerous default because it hides client bugs and can widen query scope unexpectedly.
- Does it behave the same on MySQL and PostgreSQL, and how do I see the generated SQL?
- String comparison semantics and JSON column operators differ between MySQL and PostgreSQL, so test against every database engine in your fleet. The emitted SQL is opaque unless you log it, and you cannot optimize what you cannot see, so log queries in non-production environments and inspect the SQL produced by three-level nested filters. Ideally write tests that pin that generated behavior so a future package upgrade cannot silently change it.
- Is asseco-voice/laravel-json-query-builder actively maintained?
- The signals are weak: roughly 24 stars, a low package score, and a last release around March 2024. Assume there is no upstream roadmap and plan accordingly, including the ability to fork and patch. Before adopting, identify the upstream maintainer and their stated commitment level, and confirm the repository accepts issues and pull requests.
- What are the alternatives to laravel-json-query-builder?
- Spatie Query Builder and hand-rolled query objects are the usual alternatives, and both can sit behind the same internal QueryFilter interface. That interface is the important part: it lets you pilot the JSON package on one endpoint, gather telemetry for a couple of sprints, and switch implementations without touching controllers. Because adoption is low and the DSL is vendor-owned, keep the decision reversible from day one.
Weaver
How can I help you explore Laravel packages today?