Sorting

Declare sortable fields with allowedSorts(). A bare string becomes AllowedSort::field(); AllowedSort::custom() plugs in your own Sort:

use RoundlyConsulting\QueryBuilder\AllowedSort;

->allowedSorts(
    'title',                                     // shorthand for AllowedSort::field('title')
    AllowedSort::field('popularity', 'views'),   // sort=-popularity → ORDER BY views DESC
    AllowedSort::custom('length', new TitleLengthSort),
)
->defaultSort('-created_at')                     // applied only when no sort param is present

Sort syntax

• sort=title sorts ascending; a leading - (sort=-title) sorts descending.
• sort=-created_at,name applies several sorts, left to right.
• A repeated column collapses to its first occurrence — sort=title,-title sorts by title ascending, once.
• At most limits.max_sorts columns are applied (default 5), counted after duplicates are removed. Only allow-listed sorts count, so in ignore mode an unknown token never crowds out a valid one behind it.

Default sort

defaultSort() takes the same syntax — a - prefix and comma multi-sort — and runs only when the request names no sort — or, in ignore mode, none the allow-list knows. A default token that matches an allowed sort uses it (including its internal column or custom sort); any other token is ordered as a plain column, so a default does not have to be allow-listed:

QueryBuilder::for(Post::class)
    ->allowedSorts('title', AllowedSort::field('popularity', 'views'))
    ->defaultSort('-popularity,id');   // ORDER BY views DESC, id ASC

// ?sort=title → ORDER BY title ASC (the default is skipped)

Method reference

Directions are the SortDirection enum: Ascending (asc) and Descending (desc); SortDirection::fromToken('-title') resolves a token’s direction.