--- title: "Query Builder for Laravel — docs | Roundly" description: "Developer docs for Query Builder for Laravel: allow-listed filters and sorts, client-chosen operators, nullable and relation filters, capped pagination." url: https://roundly-consulting.com/open-source/docs/query-builder-for-laravel language: en --- [All packages](https://roundly-consulting.com/open-source.md) Open source # Query Builder for Laravel Install `composer require roundly-consulting/query-builder-for-laravel` Requires: PHP ^8.4 · Laravel ^12.0|^13.0 [GitHub](https://github.com/roundly-consulting/query-builder-for-laravel) [Packagist](https://packagist.org/packages/roundly-consulting/query-builder-for-laravel) [Donate (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Patreon](https://www.patreon.com/cw/roundly) ## Overview A native query builder for Laravel API list endpoints. Declare which filters and sorts an endpoint allows, and it reads the query string — filter\[…\], sort, page, per\_page — applying only those and rejecting everything else with an HTTP 400. The result is still an Eloquent builder, so you keep chaining with(), get() or paginate(). MIT-licensed, with no runtime dependencies beyond Laravel, Symfony and two small companion Roundly packages. ### What you get #### Allow-list by default Only declared filters and sorts run; anything else is an HTTP 400, or silently dropped in ignore mode. #### Rich built-in filters Exact, boolean, partial, prefix/suffix, multi-column search, comparison, scope, callback, trashed, JSON-array membership and custom filters. #### Client-chosen operators not:, contains: or gte: from a set you declare; an undeclared token stays a literal value. #### Nullable & relation filters A none sentinel, not:none, whereDoesntHave negations and value shapes that prevent PostgreSQL 500s. #### Validated pagination HasPageSize validates per\_page (422) and hard-caps it; the configured page name is applied automatically. #### Hardened by design Bound values, escaped LIKE wildcards, request limits and length-capped error messages. ### Documentation #### [Installation](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/installation.md) Install via Composer, optionally publish the config and translations, and inspect the live wire contract with artisan about. #### [Configuration](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/configuration.md) Every config key and its default — parameter names, page-size bounds, unknown-parameter modes and request limits. #### [Building queries](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/building-queries.md) Wrap a model or a prepared builder with QueryBuilder::for(), declare the allow-list, and keep chaining like any Eloquent builder. #### [Filters](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/filters.md) Every built-in filter constructor — exact, boolean, partial, prefix/suffix, scope, callback, trashed and custom — plus value normalisation. #### [Search across columns](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/search.md) One search box across several columns with search() — a literal phrase, one grouped OR, NULL-safe, and kind to PostgreSQL trigram indexes. #### [Operator filters](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/operator-filters.md) Fixed server-side comparisons with operator(), and client-chosen operators such as not:, contains: and gte: with operators(). #### [Nullable, relation & JSON filters](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/nullable-relation-filters.md) Filter nullable columns with a none sentinel, to-many relations with whereDoesntHave negations, and JSON array columns by membership. #### [Value shapes](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/value-shapes.md) Declare a FilterValueShape on typed columns so a malformed uuid or id returns an empty result instead of a PostgreSQL 500. #### [Validating filter values](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/validation.md) Wrap your validation rules in FilterValue so operator prefixes and sentinels are stripped before the rules run. #### [Sorting](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/sorting.md) Allow-list sort fields, map public names to columns, sort by several columns and set a default order. #### [Pagination](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/pagination.md) Validate and hard-cap per\_page with the HasPageSize FormRequest trait; the configured page name is applied automatically. #### [Wire contract](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/wire-contract.md) The frozen query-string syntax for filters, operators, sorts and pagination, and the status code each mistake returns. #### [Unknown parameters & errors](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/unknown-parameters.md) Un-allow-listed filters and sorts return HTTP 400 with a translatable, length-capped message — or are dropped in ignore mode. #### [Custom filters & sorts](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/custom-filters-sorts.md) Implement the Filter or Sort contract for bespoke logic, and parse the operator wire in callbacks with RequestedOperator::split(). #### [Security model](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/security.md) How the package keeps request input away from SQL: allow-lists, bound values, escaped wildcards, request limits and capped error output. #### [Testing](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/testing.md) Drive the builder with Request::create() in unit tests, and assert 400 and 422 responses on your endpoints. #### [Requirements](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/requirements.md) PHP 8.4+, Laravel 12 or 13, and two companion packages installed automatically — no migrations or extra PHP extensions. ## Show your open-source love This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented. [More ways to support, including crypto](https://roundly-consulting.com/support-us.md) By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md). [Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly) ## Want this built into your product? We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours. [Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source.md)