Pagination
Mix HasPageSize into a FormRequest to validate and resolve the page size:
use Illuminate\Foundation\Http\FormRequest;
use RoundlyConsulting\QueryBuilder\Concerns\HasPageSize;
final class ListPostsRequest extends FormRequest
{
use HasPageSize;
public function rules(): array
{
return [
...$this->pageSizeRules(),
// your other rules
];
}
}$posts = QueryBuilder::for(Post::class)
->allowedFilters('status')
->paginate($request->perPage());What the trait gives you
| Method | Returns |
|---|---|
pageSizeRules() | ['per_page' => ['nullable', 'integer', 'min:1', 'max:100']] — merge into rules(). |
perPage() | The requested size, hard-capped at max_per_page; default_per_page when absent or invalid. |
pageName() | The configured pagination.page_name. |
per_page above max_per_page, below 1, or non-integer yields a 422. perPage() also hard-caps at max_per_page and falls back to default_per_page as defence in depth.
Page parameter name
paginate() and simplePaginate() on a QueryBuilder are handed the configured pagination.page_name automatically, so renaming it in config is honoured on the wire and in the generated links. Pass pageName: yourself to override it, or read it from the request when you build a paginator by hand:
// config/query-builder.php
'pagination' => [
'page_name' => 'p',
// ...
],
// QueryBuilder applies it: ?p=2, and the paginator links use ?p=
QueryBuilder::for(Post::class)->paginate($request->perPage());
// A paginator you build yourself
Post::query()->paginate($request->perPage(), pageName: $request->pageName());A page name passed explicitly — as pageName: or the third positional argument — always wins. Cursor pagination is out of scope.
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 cryptoBy donating, you agree to our donation terms.
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.