Filters

Declare filters with the AllowedFilter constructors. Each reads one filter[<name>] parameter; the full reference:

Public names vs columns

Every constructor takes an optional internal name, so a public request key can map to a different column or scope — your schema never leaks into the URL and can change without breaking clients:

->allowedFilters(
    AllowedFilter::exact('state', 'status'),     // filter[state]=…  → where('status', …)
    AllowedFilter::partial('q', 'title'),        // filter[q]=…      → title LIKE %…%
    AllowedFilter::scope('live', 'published'),   // filter[live]=…   → published(…)
)

Exact and text matches

->allowedFilters(
    'status',                               // shorthand for AllowedFilter::exact('status')
    AllowedFilter::partial('title'),        // filter[title]=hello        → %hello%
    AllowedFilter::beginsWith('sku'),       // filter[sku]=AB             → AB%
    AllowedFilter::endsWith('email'),       // filter[email][email protected] → %@example.com
)

// ?filter[status]=published,draft → whereIn('status', ['published', 'draft'])
// ?filter[title]=a,b              → title LIKE %a% OR title LIKE %b%

exact() compares with = and turns a comma list into whereIn. partial(), beginsWith() and endsWith() use ILIKE on PostgreSQL and LIKE elsewhere. User-typed % and _ are escaped and matched with an explicit ESCAPE clause on SQLite, MySQL and PostgreSQL, so a value can never widen the match. A comma list becomes a grouped OR.

Case folding is the engine’s

partial(), beginsWith(), endsWith() and the contains / ncontains / starts operators ignore letter case the way the database does, and the three engines differ outside plain ASCII:

Scopes

scope() calls the model scope named after the filter (camel-cased, so views_between calls viewsBetween). By default the normalised value is passed as a single argument — filter[published]=a,b calls the scope with ['a', 'b']:

// App\Models\Post
public function scopePublished(Builder $query, bool $published): void
{
    $query->where('status', $published ? 'published' : 'draft');
}

public function scopeViewsBetween(Builder $query, int $min, int $max): void
{
    $query->whereBetween('views', [$min, $max]);
}

// Controller
->allowedFilters(
    AllowedFilter::scope('published', booleans: true),   // filter[published]=false      → published(false)
    AllowedFilter::scope('views_between', spread: true), // filter[views_between]=10,100 → viewsBetween(10, 100)
)

Scope spreading is opt-in. A single argument stops the request from controlling how many arguments a scope receives — otherwise it could inject an optional parameter of a scope such as scopeSearch($q, $term, $column = 'title'). Enable spread: true only for a scope you own whose arguments map to a comma/array value.

Boolean values

true and false stay text — a title search for “false” is a search — unless the filter says its value is a boolean: AllowedFilter::boolean(), a FilterValueShape::Boolean, or booleans: true on scope(), callback() or custom(). Those turn each true/false/1/0 (any case) into a real boolean and leave every other value as it was. Without it a scope receives the string, and PHP reads 'false' as truthy:

// Post::scopePublished(Builder $query, bool $published)
->allowedFilters(
    AllowedFilter::boolean('active'),                        // filter[active]=false
    AllowedFilter::scope('published', booleans: true),       // filter[published]=false → false
)

// ?filter[active]=TRUE        → active = true
// ?filter[active]=0           → active = false
// ?filter[active]=true,false  → either
// ?filter[active]=maybe       → matches nothing (no driver error)

boolean() is shorthand for operators() with no operators and FilterValueShape::Boolean — use that directly to also offer not: (see Value shapes). A value that is not a boolean spelling matches nothing instead of reaching the driver, where PostgreSQL would answer with an error.

Callbacks

use Illuminate\Database\Eloquent\Builder;

->allowedFilters(
    AllowedFilter::callback('min_views', function (Builder $query, mixed $value, string $property): void {
        $query->where('views', '>=', $value);
    }),
)

The callback receives the query, the normalised value and the internal name. For a plain comparison, prefer AllowedFilter::operator() over a hand-written callback (see Operator filters).

Soft deletes

// Post uses Illuminate\Database\Eloquent\SoftDeletes
->allowedFilters(AllowedFilter::trashed())

// ?filter[trashed]=with  → include soft-deleted rows
// ?filter[trashed]=only  → only soft-deleted rows
// any other value        → the default: non-trashed rows only

trashed() needs a model using SoftDeletes. The only mode honours a custom soft-delete column. The filter name defaults to trashed; pass another name as the first argument.

Value normalisation

Values are normalised once, before any filter runs — a comma list becomes an array and one level of array nesting is flattened; the values themselves stay strings:

Request limits bound the work: at most limits.max_filter_values items per value (default 50) and limits.max_value_length characters per item (default 255) — the excess is dropped or truncated.