Wire contract

The query-string format is a frozen contract — front ends and bookmarks keep working as the package evolves. With the default parameter names:

Concern	Syntax	Semantics
Filter	`filter[<name>]=<value>`	One param per filter; <name> is the allow-list key.
Multi-value filter	`filter[<name>]=a,b,c`	Comma-split → array; exact → whereIn.
Array filter value	`filter[<name>][]=a`	One level of nesting is flattened into the list.
Boolean filter value	`filter[<name>]=true / false`	A real bool (also 1/0, any case) only for a filter that opts in — boolean(), FilterValueShape::Boolean, booleans: true. Every other filter receives the text.
Operator	`filter[<name>]=<token>:<value>`	operators(), nullable(), relation() and jsonContains() only; an undeclared token stays part of the value.
Unset	`filter[<name>]=none / not:none`	The sentinel of nullable(), and of relation() when given one.
Sort asc / desc	`sort=field / sort=-field`	Leading - = descending.
Multi-sort	`sort=-created_at,name`	Applied left → right; duplicate columns collapse to the first, capped by limits.max_sorts (allow-listed sorts only).
Pagination	`page=<n>&per_page=<n>`	Laravel paginator names; per_page validated by HasPageSize.
Unknown filter/sort key	Any key not allow-listed	HTTP 400 (or dropped in ignore mode; with every sort dropped, the default sort applies).
Invalid per_page	> max, < 1, non-integer	HTTP 422.

A full request

A request using every part of the contract (the endpoint must declare each filter and sort):

GET /posts?filter[status]=not:draft,archived&filter[title]=laravel&filter[project]=none&sort=-created_at,title&page=2&per_page=25

Parameter names come from parameters.* and pagination.* in the config; change them only together with your front end.

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.

By donating, you agree to our donation terms.

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.