---
title: "Configuration — Query Builder for Laravel | Roundly"
description: "Every config key and its default — parameter names, page-size bounds, unknown-parameter modes and request limits."
url: https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/configuration
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Query Builder for Laravel](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel.md)

# Configuration

The package works with zero host configuration. The published config/query-builder.php in full:

```php
return [
    'parameters' => [
        'filter' => 'filter',   // filter[<name>]=<value>
        'sort'   => 'sort',     // sort=-created_at,name
    ],

    'pagination' => [
        'page_name'        => 'page',
        'per_page_name'    => 'per_page',
        'default_per_page' => 20,
        'max_per_page'     => 100,
    ],

    'mode' => [
        'unknown_filter' => 'reject',
        'unknown_sort'   => 'reject',
    ],

    'limits' => [
        'max_filter_values' => 50,   // most comma/array items per filter value
        'max_value_length'  => 255,  // most characters per individual value
        'max_sorts'         => 5,    // most allow-listed sort columns applied
    ],
];
```

## Every key

| Key | Type | Default | Purpose |
| --- | --- | --- | --- |
| `parameters.filter` | string | `filter` | Query-string key that holds the filter bag. A string; blank = not set → filter. |
| `parameters.sort` | string | `sort` | Query-string key that holds the sort string. A string; blank = not set → sort. |
| `pagination.page_name` | string | `page` | Paginator page parameter — applied automatically by paginate()/simplePaginate() on a QueryBuilder, and readable via pageName() on a HasPageSize request. |
| `pagination.per_page_name` | string | `per_page` | Page-size parameter name (used by HasPageSize). |
| `pagination.default_per_page` | int | `20` | Page size used when per\_page is absent or invalid. At least 1 and at most max\_per\_page — left unset, it is 20 or max\_per\_page, whichever is lower; set explicitly above max\_per\_page, it throws. |
| `pagination.max_per_page` | int | `100` | Upper bound — per\_page above it is a 422; also a hard cap. At least 1. |
| `mode.unknown_filter` | string | `reject` | reject (HTTP 400) or ignore (drop the key) for un-allow-listed filters. |
| `mode.unknown_sort` | string | `reject` | reject (HTTP 400) or ignore (drop the key) for un-allow-listed sorts. When ignore drops every requested sort, defaultSort() applies. |
| `limits.max_filter_values` | int | `50` | Comma/array items kept per filter value; extras are dropped (DoS guard). At least 1. |
| `limits.max_value_length` | int | `255` | Characters kept per individual filter value; longer values are truncated. At least 1. |
| `limits.max_sorts` | int | `5` | Sort columns applied, after duplicates are removed keeping the first. Only allow-listed sorts count, so a token dropped in ignore mode never takes a valid one’s place. At least 1. |

## Notes

- parameters.\* — the shipped defaults are the frozen wire contract; change them only if your front end changes too.
- Every key is read strictly: a key that is not set — absent, null or blank (a host’s KEY=) — takes its default, and any other invalid value throws package-toolkit’s InvalidConfigurationException naming the key. Parameter names must be strings, limits and page sizes whole numbers of at least 1.
- mode.\* — exactly reject or ignore. A typo throws rather than quietly falling back to reject.
- limits.\* — excess items are dropped and over-long values truncated; the request is never rejected for it. A junk limit throws instead of being cast and clamped to 1.
- There are no env variables — override values by publishing the config file.

## 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/docs/query-builder-for-laravel.md)