Laravel Query Builder

https://github.com/spatie/laravel-query-builder
Admin
Build Eloquent queries from API requests, allowing filtering, including relations, sorting, and...
Tokens:41,277
Snippets:331
Trust Score:-
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Starting from Existing Queries

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Starting from existing queries: pass an Eloquent query or a relation to QueryBuilder::for. Both examples filter by name and retrieve results.

```php
// From an Eloquent query
QueryBuilder::for(User::where('active', true))
    ->allowedFilters('name')
    ->get();
```

```php
// From a relation
QueryBuilder::for($team->users())
    ->allowedFilters('name')
    ->get();
```

--------------------------------

### Install package via Composer

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Run this command to install the spatie/laravel-query-builder package via Composer.

```bash
composer require spatie/laravel-query-builder
```

--------------------------------

### Example URL for scope filter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows the URL format to trigger the `startsBefore` scope filter. The filter value is passed as a date.

```text
GET /events?filter[starts_before]=2018-01-01
```

--------------------------------

### Works together nicely with existing queries

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Start from an existing Eloquent Builder instance and chain additional query builder methods. The example shows using withTrashed(), allowedIncludes(), and where() on the QueryBuilder.

```php
$query = User::where('active', true);

$userQuery = QueryBuilder::for($query) // start from an existing Builder instance
    ->withTrashed() // use your existing scopes
    ->allowedIncludes('posts', 'permissions')
    ->where('score', '>', 42); // chain on any of Laravel's query builder methods
```

--------------------------------

### Example URL for scope filter with multiple parameters

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows the URL format to pass multiple parameters to a scope filter using a comma-separated list and dot-notation for relationships.

```text
GET /events?filter[schedule.starts_between]=2018-01-01,2018-12-31
```

--------------------------------

### Example request URL with camelCase includes and nested filters

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the request URL format for v4 and later, where requested names are passed as-is without automatic camel-casing or pluralization.

```http
GET /api/users
        ?include=latestPosts,friendRequests
        &filter[homeAddress.city]=Antwerp
        &fields[related_models.test_models]=id,name
```

--------------------------------

### Basic groupOr Filter Usage

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Groups multiple partial filters under a single 'q' parameter using OR conjunction. The example shows the PHP setup and the resulting SQL query for the URL /users?filter[q]=John.

```php
use Spatie\QueryBuilder\AllowedFilter;

QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('full_name'),
        ]),
    );
```

```sql
WHERE (LOWER(name) LIKE LOWER('%John%') OR LOWER(full_name) LIKE LOWER('%John%'))
```

--------------------------------

### groupAnd Filter Usage

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Groups multiple partial filters under a single 'match' parameter using AND conjunction. The example shows the PHP setup and the resulting SQL query for the URL /users?filter[match]=John.

```php
AllowedFilter::groupAnd('match', [
    AllowedFilter::partial('name'),
    AllowedFilter::partial('full_name'),
]);
```

```sql
WHERE (LOWER(name) LIKE LOWER('%John%') AND LOWER(full_name) LIKE LOWER('%John%'))
```

--------------------------------

### Basic QueryBuilder Usage

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Basic usage of QueryBuilder to filter, sort, include, and select fields for a User model. The example shows the query parameters that map to each method.

```php
use Spatie\QueryBuilder\QueryBuilder;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\AllowedInclude;
use Spatie\QueryBuilder\AllowedSort;

// GET /users?filter[name]=John&sort=-created_at&include=posts
$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name', 'created_at')
    ->allowedIncludes('posts', 'permissions')
    ->allowedFields('id', 'name', 'email')
    ->get();
```

--------------------------------

### Select fields for a query: /users?fields[users]=id,email

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Use allowedFields('id', 'email') to limit the columns returned. The example returns users with only their id and email attributes set.

```php
$users = QueryBuilder::for(User::class)
    ->allowedFields('id', 'email')
    ->get();

// the fetched `User`s will only have their id & email set
```

--------------------------------

### Basic filtering with allowedFilters

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows how to filter users by name and email using partial matching. The `allowedFilters` method accepts column names and automatically applies partial filters. The example uses query parameters `filter[name]=john` and `filter[email]=gmail`.

```php
// GET /users?filter[name]=john&filter[email]=gmail

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->get();

// $users will contain all users with "john" in their name AND "gmail" in their email address
```

--------------------------------

### Include relations based on a request: /users?include=posts

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Use allowedIncludes('posts') to eager-load the posts relationship for the returned users. The example returns all users with their posts loaded.

```php
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts')
    ->get();

// all `User`s with their `posts` loaded
```

--------------------------------

### Combining Group with Top-Level Filter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows how a group filter combines with a top-level filter of the same name using AND. Includes the PHP setup and the resulting SQL for the URL /users?filter[name]=Ali&filter[q]=John.

```php
->allowedFilters(
    AllowedFilter::partial('name'),
    AllowedFilter::groupOr('q', [
        AllowedFilter::partial('name'),
        AllowedFilter::partial('full_name'),
    ]),
)
```

```sql
WHERE LOWER(name) LIKE LOWER('%Ali%')
  AND (LOWER(name) LIKE LOWER('%John%') OR LOWER(full_name) LIKE LOWER('%John%'))
```

--------------------------------

### Example request parsing with custom delimiter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/advanced-usage/multi-value-delimiter.md

Shows how a request with pipe-separated values is parsed when the global delimiter is set to '|'. The filter value becomes an array of strings.

```php
// filters: [ 'voltage' => [ '12,4V', '4,7V', '2,1V' ]]
```

--------------------------------

### Ignore array of values and skip filter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

When all requested values are ignored, the filter is not applied. This example ignores both 'ignored' and 'ignored_too'.

```php
// GET /user?filter[name]=ignored,ignored_too

QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('name')->ignore(['ignored', 'ignored_too']),
    )
    ->get();
// Filter does not get applied because all requested values are ignored.
```

--------------------------------

### Multiple Independent Filter Groups

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows how to define multiple independent OR groups that are AND-joined to each other. Includes the PHP setup and the resulting SQL for the URL /users?filter[q]=John&filter[loc]=ist.

```php
->allowedFilters(
    AllowedFilter::groupOr('q', [
        AllowedFilter::partial('name'),
        AllowedFilter::partial('full_name'),
    ]),
    AllowedFilter::groupOr('loc', [
        AllowedFilter::partial('city'),
        AllowedFilter::partial('country'),
    ]),
)
```

```sql
WHERE (LOWER(name) LIKE LOWER('%John%') OR LOWER(full_name) LIKE LOWER('%John%'))
  AND (LOWER(city) LIKE LOWER('%ist%') OR LOWER(country) LIKE LOWER('%ist%'))
```

--------------------------------

### Filter alias with AllowedFilter::exact()

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shows how to use an alias for a filter to avoid exposing a database column name. The example filters by the 'name' parameter but maps it to the 'user_passport_full_name' column.

```php
use Spatie\QueryBuilder\AllowedFilter;

// GET /users?filter[name]=John

$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('name', 'user_passport_full_name')) // will filter by the `user_passport_full_name` column
    ->get();
```

--------------------------------

### Sort by multiple properties with comma

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/sorting.md

Sorts by multiple properties by separating them with a comma in the sort parameter. The example sorts by name ascending and street descending.

```php
// GET /users?sort=name,-street

$users = QueryBuilder::for(User::class)
    ->allowedSorts('name', 'street')
    ->get();

// $users will be sorted by name in ascending order with a secondary sort on street in descending order.
```

--------------------------------

### AllowedFilter::trashed() usage

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Use AllowedFilter::trashed() to filter soft-deleted models. The filter responds to the 'with', 'only', and any other value to include, return only trashed, or exclude trashed records respectively. The example shows a GET request to /bookings?filter[trashed]=only returning only soft-deleted models.

```php
QueryBuilder::for(Booking::class)
    ->allowedFilters(
        AllowedFilter::trashed(),
    );

// GET /bookings?filter[trashed]=only will only return soft deleted models
```

--------------------------------

### Create a custom include with AllowedInclude::custom

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Define a custom include class implementing IncludeInterface and register it with AllowedInclude::custom(). The __invoke method receives the query builder and relation name, enabling custom queries like withAggregate. The example adds a comments_sum_votes property to each post.

```php
use Spatie\QueryBuilder\Includes\IncludeInterface;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use App\Models\Post;

/**
 * @implements IncludeInterface<Model>
 */
class AggregateInclude implements IncludeInterface
{
    protected string $column;

    protected string $function;

    public function __construct(string $column, string $function)
    {
        $this->column = $column;

        $this->function = $function;
    }

    public function __invoke(Builder $query, string $relations)
    {
        $query->withAggregate($relations, $this->column, $this->function);
    }
}

// In your controller for the following request:
// GET /posts?include=comments_sum_votes

$posts = QueryBuilder::for(Post::class)
    ->allowedIncludes(
        AllowedInclude::custom('comments_sum_votes', new AggregateInclude('votes', 'sum'), 'comments'),
    )
    ->get();

// every post in $posts will contain a `comments_sum_votes` property
```

--------------------------------

### Sort a query based on a request: /users?sort=id

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Use allowedSorts('id') to sort the results by the given field. The example returns all users sorted by ascending id.

```php
$users = QueryBuilder::for(User::class)
    ->allowedSorts('id')
    ->get();

// all `User`s sorted by ascending id
```

--------------------------------

### Relation Filter with Dot Notation

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Filters by a related model property using dot notation. The example filters users by the title of their posts.

```php
// GET /users?filter[posts.title]=Laravel
QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::partial('posts.title'));
```

--------------------------------

### Ignore multiple values with ignore()

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

The ignore() method accepts one or more values, each possibly an array. This example shows valid calls: ignore('should_be_ignored'), ignore(null, '-1'), and ignore([null, 'ignore_me', 'also_ignored']).

```php
ignore('should_be_ignored')
```

```php
ignore(null, '-1')
```

```php
ignore([null, 'ignore_me', 'also_ignored'])
```

--------------------------------

### Field Selection with allowedFields

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Use allowedFields to restrict which fields are returned for a model. The example shows selecting id, name, and email for users, while including posts with their id and title fields.

```php
// GET /users?fields[users]=id,name&fields[posts]=id,title&include=posts
QueryBuilder::for(User::class)
    ->allowedFields('id', 'name', 'email')
    ->allowedIncludes('posts')
    ->get();
```

--------------------------------

### AllowedFilter::callback() with arrow function (PHP 7.4)

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Shorter version of the callback filter using a PHP 7.4 arrow function. The example is equivalent to the previous one but uses fn (Builder $query) => $query->whereHas('posts').

```php
QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::callback('has_posts', fn (Builder $query) => $query->whereHas('posts')),
    );
```

--------------------------------

### Using a base query with QueryBuilder

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/advanced-usage/extending-query-builder.md

Pass a base query to QueryBuilder::for() instead of a model class, then chain allowedIncludes and other Laravel query methods. This example filters users by id 42, includes posts, and retrieves the first matching user.

```php
QueryBuilder::for(User::where('id', 42)) // base query instead of model
    ->allowedIncludes('posts')
    ->where('activated', true) // chain on any of Laravel's query methods
    ->first(); // we only need one specific user
```

--------------------------------

### Group multiple filters with OR/AND using AllowedFilter::groupOr

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Use AllowedFilter::groupOr() to group multiple partial filters under a single request parameter. The example shows how the query is built for /users?filter[q]=John and how it combines with an additional filter[name]=Doe. AllowedFilter::groupAnd() is also available.

```php
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::partial('name'),
        AllowedFilter::partial('full_name'),
        AllowedFilter::groupOr('q', [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('full_name'),
        ]),
    )
    ->get();

// /users?filter[q]=John
//   → WHERE (name LIKE '%John%' OR full_name LIKE '%John%')
//
// /users?filter[q]=John&filter[name]=Doe
//   → WHERE name LIKE '%Doe%' AND (name LIKE '%John%' OR full_name LIKE '%John%')
```

--------------------------------

### Filter a query based on a request: /users?filter[name]=John

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Use QueryBuilder::for() with allowedFilters('name') to filter users by a request parameter. The example returns all users whose name contains the string 'John'.

```php
use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

// all `User`s that contain the string "John" in their name
```

--------------------------------

### Exact filter with AllowedFilter::exact

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Use AllowedFilter::exact('property_name') in the allowedFilters() method to filter by exact values. The query builder automatically maps '1', '0', 'true', and 'false' as boolean values and a comma-separated list as an array. The example shows filtering by exact name and by ID/admin with boolean mapping.

```php
use Spatie\QueryBuilder\AllowedFilter;

// GET /users?filter[name]=John%20Doe
$users = QueryBuilder::for(User::class)
    ->allowedFilters(AllowedFilter::exact('name'))
    ->get();

// only users with the exact name "John Doe"
```

```php
use Spatie\QueryBuilder\AllowedFilter;

// GET /users?filter[id]=1,2,3,4,5&filter[admin]=true

$users = QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('id'),
        AllowedFilter::exact('admin'),
    )
    ->get();

// $users will contain all admin users with id 1, 2, 3, 4 or 5
```

--------------------------------

### AllowedFilter::callback() with closure

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Use AllowedFilter::callback() to define a custom filter with a callable that receives Builder $query, mixed $value, and string $name. The example adds a whereHas constraint to filter users that have posts.

```php
QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::callback('has_posts', function (Builder $query, $value) {
            $query->whereHas('posts');
        }),
    );
```

--------------------------------

### Run package tests

Source: https://github.com/spatie/laravel-query-builder/blob/main/README.md

Run this command to execute the package's test suite.

```bash
composer test
```

--------------------------------

### Configure allowed includes with various types

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Configure allowed includes for eager loading, counting, existence checks, aliases, and custom callbacks. The comment shows the resulting include query string.

```php
use Spatie\QueryBuilder\AllowedInclude;

QueryBuilder::for(User::class)
    ->allowedIncludes(
        'posts',                                     // Eager loads posts (also allows postsCount and postsExists)
        'posts.comments',                            // Nested eager loading
        AllowedInclude::count('commentsCount'),      // Only withCount, no full relation
        AllowedInclude::exists('postsExists'),       // Only withExists
        AllowedInclude::relationship('profile', 'userProfile'), // Alias
        AllowedInclude::callback('latestPost', fn ($query) => $query->latestOfMany()),
    );

// GET /users?include=posts,commentsCount,postsExists
```

--------------------------------

### Publish Config File

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/installation-setup.md

Publishes the configuration file to the application's config directory. This is optional and allows customization of query parameters and other settings.

```bash
php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider" --tag="query-builder-config"
```

--------------------------------

### Config suffixes consolidation: before and after

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the consolidation of count_suffix and exists_suffix into a single suffixes array with new aggregate suffixes.

```php
// Before
'count_suffix' => 'Count',
'exists_suffix' => 'Exists',
```

```php
// After
'suffixes' => [
    'count' => 'Count',
    'exists' => 'Exists',
    'min' => 'Min',
    'max' => 'Max',
    'sum' => 'Sum',
    'avg' => 'Avg',
],
```

--------------------------------

### Disallowed sort throws InvalidSortQuery

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/sorting.md

Attempting to sort by a property not in allowedSorts() throws an InvalidSortQuery exception. The example shows sorting by 'password' which is not allowed.

```php
// GET /users?sort=password
$users = QueryBuilder::for(User::class)
    ->allowedSorts('name')
    ->get();

// Will throw an `InvalidSortQuery` exception as `password` is not an allowed sorting property
```

--------------------------------

### Controller with Full Query Builder

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Shows a typical controller method using the query builder with allowed filters, sorts, includes, fields, and a default sort, then paginates the results and returns a resource collection.

```php
class UsersController
{
    public function index()
    {
        $users = QueryBuilder::for(User::class)
            ->allowedFilters(
                AllowedFilter::partial('name'),
                AllowedFilter::exact('email'),
                AllowedFilter::scope('active'),
            )
            ->allowedSorts('name', 'created_at')
            ->allowedIncludes('posts', 'permissions')
            ->allowedFields('id', 'name', 'email')
            ->defaultSort('name')
            ->paginate();

        return UserResource::collection($users);
    }
}
```

--------------------------------

### Dynamic Arrays with Variadic Methods

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Demonstrates using variadic methods with dynamic arrays for allowedFilters and allowedSorts, spreading the arrays into the method calls.

```php
$filters = ['name', 'email'];
$sorts = ['name', 'created_at'];

QueryBuilder::for(User::class)
    ->allowedFilters(...$filters)
    ->allowedSorts(...$sorts);
```

--------------------------------

### Default Config File

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/installation-setup.md

Default configuration file for the package. It defines query parameter names, delimiter, suffixes for aggregates, exception disabling flags, and naming conversion options. Customize these settings after publishing the config.

```php
return [

    /*
     * By default the package will use the `include`, `filter`, `sort`
     * and `fields` query parameters as described in the readme.
     *
     * You can customize these query string parameters here.
     */
    'parameters' => [
        'include' => 'include',

        'filter' => 'filter',

        'sort' => 'sort',

        'fields' => 'fields',

        'append' => 'append',
    ],

    /*
     * The delimiter used to split array values in query parameters.
     * For example: ?filter[name]=John,Jane uses ',' as delimiter.
     */
    'delimiter' => ',',

    /*
     * Whether filter values should be split by the configured delimiter.
     */
    'filter_value_splitting_enabled' => true,

    /*
     * Related model aggregates are included using the relationship name suffixed with these strings.
     * For example: GET /users?include=postsCount or GET /users?include=postsViewsSum
     */
    'suffixes' => [
        'count' => 'Count',
        'exists' => 'Exists',
        'min' => 'Min',
        'max' => 'Max',
        'sum' => 'Sum',
        'avg' => 'Avg',
    ],

    /*
     * By default the package will throw an `InvalidFilterQuery` exception when a filter in the
     * URL is not allowed in the `allowedFilters()` method.
     */
    'disable_invalid_filter_query_exception' => false,

    /*
     * By default the package will throw an `InvalidSortQuery` exception when a sort in the
     * URL is not allowed in the `allowedSorts()` method.
     */
    'disable_invalid_sort_query_exception' => false,

    /*
     * By default the package will throw an `InvalidIncludeQuery` exception when an include in the
     * URL is not allowed in the `allowedIncludes()` method.
     */
    'disable_invalid_include_query_exception' => false,

    /*
     * By default, the package expects relationship names to be snake case plural when using fields[relationship].
     * For example, fetching the id and name for a userOwner relation would look like this:
     * GET /users?include=userOwner&fields[user_owners]=id,name
     *
     * Set this to `false` if you don't want that and keep the requested relationship names as-is and allows you to
     * request the fields using a camelCase relationship name:
     * GET /users?include=userOwner&fields[userOwner]=id,name
     */
    'convert_relation_names_to_snake_case_plural' => true,

    /*
     * This is an alternative to the previous option if you don't want to use default snake case plural for fields[relationship].
     * It resolves the table name for the related model using the Laravel model class and, based on your chosen strategy,
     * matches it with the fields[relationship] provided in the request.
     *
     * Set this to one of `snake_case`, `camelCase` or `none` if you want to enable table name resolution in addition to the relation name resolution.
     * `snake_case` => Matches table names like 'topOrders' to `fields[top_orders]`
     * `camelCase` => Matches table names like 'top_orders' to 'fields[topOrders]`
     * `none` => Uses the exact table name
     */
    'convert_relation_table_name_strategy' => null,

    /*
     * By default, the package expects the field names to match the database names
     * For example, fetching the field named firstName would look like this:
     * GET /users?fields=firstName
     *
     * Set this to `true` if you want to convert the firstName into first_name for the underlying query
     */
    'convert_field_names_to_snake_case' => false,
];
```

--------------------------------

### Configuration for query-builder.php

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Configuration file published to config/query-builder.php. Allows customizing query parameter names, the array delimiter, include suffixes for aggregates, and disabling exceptions for invalid queries.

```php
return [
    // Custom query parameter names
    'parameters' => [
        'include' => 'include',
        'filter' => 'filter',
        'sort' => 'sort',
        'fields' => 'fields',
    ],

    // Array value delimiter
    'delimiter' => ',',

    // Include suffixes (for count, exists, and aggregate includes)
    'suffixes' => [
        'count' => 'Count',
        'exists' => 'Exists',
        'min' => 'Min',
        'max' => 'Max',
        'sum' => 'Sum',
        'avg' => 'Avg',
    ],

    // Disable exception throwing for invalid queries
    'disable_invalid_filter_query_exception' => false,
    'disable_invalid_sort_query_exception' => false,
    'disable_invalid_include_query_exception' => false,
];
```

--------------------------------

### Config delimiter key

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the new 'delimiter' config key in the config file.

```php
// config/query-builder.php
'delimiter' => ',',
```

--------------------------------

### Disallowed fields throw InvalidFieldQuery exception

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/selecting-fields.md

Attempting to select a field not specified in allowedFields throws an InvalidFieldQuery exception. The example shows allowedFields('name') and a request for email.

```php
$users = QueryBuilder::for(User::class)
    ->allowedFields('name')
    ->get();

// GET /users?fields[users]=email will throw an `InvalidFieldQuery` exception as `email` is not an allowed field.
```

--------------------------------

### Default includes using with(), withCount(), withExists()

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Shows how to always include relationships using Laravel's `with()` method, and also `withCount()` and `withExists()`. The package itself has no default include mechanism.

```php
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('friends')
    ->with('posts') // posts will always by included, friends can be requested
    ->withCount('posts')
    ->withExists('posts')
    ->get();
```

--------------------------------

### Implement custom include with IncludeLatestPost

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Implements the IncludeInterface to create a custom include that eager loads the latest post. The final line registers the custom include with AllowedInclude::custom.

```php
use Spatie\QueryBuilder\Includes\IncludeInterface;
use Illuminate\Database\Eloquent\Builder;

class IncludeLatestPost implements IncludeInterface
{
    public function __invoke(Builder $query, string $include): void
    {
        $query->with(['latestPost' => fn ($q) => $q->latest()]);
    }
}

AllowedInclude::custom('latestPost', new IncludeLatestPost());
```

--------------------------------

### Variadic parameters: before and after allowedFilters/allowedSorts/allowedIncludes/allowedFields

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the change from array arguments to variadic arguments for the allowed* methods. The before block uses arrays, the after block uses individual arguments.

```php
// Before
QueryBuilder::for(User::class)
    ->allowedFilters(['name', 'email'])
    ->allowedSorts(['name'])
    ->allowedIncludes(['posts'])
    ->allowedFields(['id', 'name']);
```

```php
// After
QueryBuilder::for(User::class)
    ->allowedFilters('name', 'email')
    ->allowedSorts('name')
    ->allowedIncludes('posts')
    ->allowedFields('id', 'name');
```

--------------------------------

### Ignore single value and filter with array

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

When filtering with an array of values, only non-ignored values are passed to the filter. If all values are ignored, the filter is not applied. This example shows ignoring 'forbidden' and filtering for 'John Doe'.

```php
// GET /user?filter[name]=forbidden,John%20Doe

QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('name')->ignore('forbidden'),
    )
    ->get();
// Returns only users where name matches 'John Doe'
```

--------------------------------

### Configure allowed sorts and default sorts

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Configure allowed sorts with aliases, custom sorts, and callbacks, plus default sort behavior. The comment shows the resulting query string for descending created_at and ascending name.

```php
use Spatie\QueryBuilder\AllowedSort;
use Spatie\QueryBuilder\Enums\SortDirection;

QueryBuilder::for(User::class)
    ->allowedSorts(
        'name',
        'created_at',
        AllowedSort::field('order', 'sort_order'),   // Alias: ?sort=order queries sort_order
        AllowedSort::custom('popular', new SortMostPopular()),
        AllowedSort::callback('random', fn ($query, $descending) => $query->inRandomOrder()),
    )
    ->defaultSort('name')
    ->defaultSorts('name', AllowedSort::field('date', 'created_at')->defaultDirection(SortDirection::Descending));

// GET /users?sort=-created_at,name (descending created_at, ascending name)
```

--------------------------------

### Use AllowedFilter::scope to filter by local scope

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Adds a scope filter for 'starts_before' to the query builder. This will apply the `startsBefore` scope to the query when the filter is used.

```php
QueryBuilder::for(Event::class)
    ->allowedFilters(
        AllowedFilter::scope('starts_before'),
    )
    ->get();
```

--------------------------------

### Basic include with allowedIncludes('posts')

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Loads the 'posts' relationship on User models when the `include=posts` query parameter is present. The `allowedIncludes()` method must explicitly allow the relationship name.

```php
// GET /users?include=posts

$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts')
    ->get();

// $users will have all their `posts()` related models loaded
```

--------------------------------

### Define a local scope for filtering

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Defines a `scopeStartsBefore` local scope that filters records where `starts_at` is before or on a given date. This scope is used with the `AllowedFilter::scope` filter.

```php
public function scopeStartsBefore(Builder $query, $date): Builder
{
    return $query->where('starts_at', '<=', Carbon::parse($date));
}
```

--------------------------------

### Wildcard Allow-All with allowedFilters('*')

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Wildcard allow-all: permits any requested filter, sort, or include without explicit listing. Restricted to local and testing environments.

```php
QueryBuilder::for(User::class)
    ->allowedFilters('*')
    ->allowedSorts('*')
    ->allowedIncludes('*');
```

--------------------------------

### Basic usage of allowedFields with fields query parameter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/selecting-fields.md

Fetches only the id and name fields for users using the fields query parameter and allowedFields method. The SQL output shows the resulting SELECT statement.

```php
// GET /users?fields[users]=id,name

$users = QueryBuilder::for(User::class)
    ->allowedFields('id', 'name')
    ->toSql();
```

```sql
SELECT "id", "name" FROM "users"
```

--------------------------------

### Filter interface return type: before and after

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the change in the __invoke method signature to include a void return type and mixed type hint.

```php
// Before
public function __invoke(Builder $query, $value, string $property)
```

```php
// After
public function __invoke(Builder $query, mixed $value, string $property): void
```

--------------------------------

### Include multiple relationships with allowedIncludes('posts', 'permissions')

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Loads multiple relationships by separating them with a comma in the query parameter. The `allowedIncludes()` method accepts multiple relationship names.

```php
// GET /users?include=posts,permissions
$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts', 'permissions')
    ->get();

// $users will contain all users with their posts and permissions loaded
```

--------------------------------

### Include sum and avg aggregates via query parameter

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Shows how to allow including sum and avg aggregates for the 'posts' relationship's 'views' column. The resulting users will have 'posts_sum_views' and 'posts_avg_views' properties.

```php
// GET /users?include=postsViewsSum,postsViewsAvg

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        AllowedInclude::sum('postsViewsSum', 'posts', 'views'),
        AllowedInclude::avg('postsViewsAvg', 'posts', 'views'),
    )
    ->get();

// every user in $users will contain a `posts_sum_views` and `posts_avg_views` property
```

--------------------------------

### All four aggregate include types

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Lists the four AllowedInclude aggregate methods (min, max, sum, avg) with their corresponding Laravel withMin/withMax/withSum/withAvg calls. Each requires the relationship name and column.

```php
AllowedInclude::min('postsViewsMin', 'posts', 'views');  // adds withMin('posts', 'views')
AllowedInclude::max('postsViewsMax', 'posts', 'views');  // adds withMax('posts', 'views')
AllowedInclude::sum('postsViewsSum', 'posts', 'views');  // adds withSum('posts', 'views')
AllowedInclude::avg('postsViewsAvg', 'posts', 'views');  // adds withAvg('posts', 'views')
```

--------------------------------

### Define a scope with variadic parameters

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Defines a `scopeInvitedUsers` local scope that accepts a variable number of user IDs. This allows passing an array of parameters via the filter.

```php
public function scopeInvitedUsers(Builder $query,  ...$users): Builder
{
    return $query->whereIn('id', $users);
}
```

--------------------------------

### Using constraint closures with count and sum aggregate includes

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Shows how to pass a constraint closure to AllowedInclude::count and AllowedInclude::sum to filter related models in aggregate calculations. The closure receives a Builder instance for adding query conditions.

```php
use Spatie\QueryBuilder\AllowedInclude;
use Illuminate\Database\Eloquent\Builder;

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        AllowedInclude::count('publishedPostsCount', 'posts', fn (Builder $query) => $query->where('published', true)),
        AllowedInclude::sum('publishedPostsViewsSum', 'posts', 'views', constraint: fn (Builder $query) => $query->where('published', true)),
    )
    ->get();
```

--------------------------------

### Replace request()->includes() with QueryBuilderRequest::fromRequest()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the request macro request()->includes() is replaced by QueryBuilderRequest::fromRequest($request)->includes(). The method takes no arguments.

```php
request()->includes() -> QueryBuilderRequest::fromRequest($request)->includes()
```

--------------------------------

### Define an include alias with AllowedInclude::relationship

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Use AllowedInclude::relationship('profile', 'userProfile') to alias the 'userProfile' relationship as 'profile'. This allows requests like /users?include=profile to include the userProfile relationship.

```php
use Spatie\QueryBuilder\AllowedInclude;

// GET /users?include=profile

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(AllowedInclude::relationship('profile', 'userProfile')) // will include the `userProfile` relationship
    ->get();
```

--------------------------------

### Filter Types with AllowedFilter

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Lists the available filter types: partial, exact, beginsWith, endsWith, scope, callback, default, nullable, ignore, belongsTo, and trashed. Each comment shows the SQL behavior or purpose.

```php
use Spatie\QueryBuilder\AllowedFilter;

QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::partial('name'),           // WHERE name LIKE '%value%' (default)
        AllowedFilter::exact('email'),             // WHERE email = 'value'
        AllowedFilter::beginsWith('name'),         // WHERE name LIKE 'value%'
        AllowedFilter::endsWith('name'),           // WHERE name LIKE '%value'
        AllowedFilter::scope('active'),            // Calls scopeActive()
        AllowedFilter::callback('search', fn ($query, $value) => ...),
        AllowedFilter::exact('role')->default('user'),  // Default filter value
        AllowedFilter::exact('status')->nullable(),     // Allows null values
        AllowedFilter::exact('role')->ignore('admin'),  // Ignores specific values
        AllowedFilter::belongsTo('author'),             // Filter by BelongsTo relationship
        AllowedFilter::trashed(),                       // Filter soft deletes (with, only, without)
    );
```

--------------------------------

### Per-filter delimiter: before and after

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the change from the $arrayValueDelimiter parameter to the fluent delimiter() method.

```php
// Before
AllowedFilter::exact('voltage', null, true, '|');
```

```php
// After
AllowedFilter::exact('voltage')->delimiter('|');
```

--------------------------------

### Minimal QueryBuilder for the above request

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

A minimal QueryBuilder configuration that matches the request URL, using allowedIncludes, allowedFilters, and allowedFields with the exact requested names.

```php
use Spatie\QueryBuilder\QueryBuilder;

QueryBuilder::for(User::class)
    ->allowedIncludes(['latestPosts', 'friendRequests'])
    ->allowedFilters(['homeAddress.city'])
    ->allowedFields(['related_models.test_models.id', 'related_models.test_models.name']);
```

--------------------------------

### Replace request()->sorts() with QueryBuilderRequest::fromRequest()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the request macro request()->sorts() is replaced by QueryBuilderRequest::fromRequest($request)->sorts(). The method takes no arguments.

```php
request()->sorts() -> QueryBuilderRequest::fromRequest($request)->sorts()
```

--------------------------------

### Aggregate includes for min, max, sum, avg

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Aggregate includes for min, max, sum, and avg on a relationship. The comment shows the resulting include query string.

```php
AllowedInclude::min('postsViewsMin', 'posts', 'views');   // withMin('posts', 'views')
AllowedInclude::max('postsViewsMax', 'posts', 'views');   // withMax('posts', 'views')
AllowedInclude::sum('postsViewsSum', 'posts', 'views');   // withSum('posts', 'views')
AllowedInclude::avg('postsViewsAvg', 'posts', 'views');   // withAvg('posts', 'views')

// GET /users?include=postsViewsSum,postsViewsAvg
```

--------------------------------

### Spread operator for dynamic arrays

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows how to pass dynamic arrays using the spread operator with allowedFilters().

```php
$filters = ['name', 'email'];
QueryBuilder::for(User::class)->allowedFilters(...$filters);
```

--------------------------------

### Replace request()->fields() with QueryBuilderRequest::fromRequest()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the request macro request()->fields() is replaced by QueryBuilderRequest::fromRequest($request)->fields(). The method takes no arguments.

```php
request()->fields() -> QueryBuilderRequest::fromRequest($request)->fields()
```

--------------------------------

### Replace request()->filters() with QueryBuilderRequest::fromRequest()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the request macro request()->filters() is replaced by QueryBuilderRequest::fromRequest($request)->filters(). The method takes no arguments.

```php
request()->filters() -> QueryBuilderRequest::fromRequest($request)->filters()
```

--------------------------------

### Constraint closure usage for all aggregate types

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Lists all aggregate include methods (count, exists, min, max, sum, avg) with constraint closures. For min, max, sum, and avg, the constraint must be passed as a named argument because $internalName precedes it in the method signature.

```php
AllowedInclude::count('name', 'relation', fn (Builder $query) => $query->where('active', true));
AllowedInclude::exists('name', 'relation', fn (Builder $query) => $query->where('active', true));
AllowedInclude::min('name', 'relation', 'column', constraint: fn (Builder $query) => $query->where('active', true));
AllowedInclude::max('name', 'relation', 'column', constraint: fn (Builder $query) => $query->where('active', true));
AllowedInclude::sum('name', 'relation', 'column', constraint: fn (Builder $query) => $query->where('active', true));
AllowedInclude::avg('name', 'relation', 'column', constraint: fn (Builder $query) => $query->where('active', true));
```

--------------------------------

### SortDirection enum: before and after

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the change from string constants to enum values for SortDirection. The before block uses DESCENDING, the after block uses Descending.

```php
// Before
use Spatie\QueryBuilder\Enums\SortDirection;

AllowedSort::field('name')->defaultDirection(SortDirection::DESCENDING);
```

```php
// After
use Spatie\QueryBuilder\Enums\SortDirection;

AllowedSort::field('name')->defaultDirection(SortDirection::Descending);
```

--------------------------------

### Implement custom sort with SortMostPopular

Source: https://github.com/spatie/laravel-query-builder/blob/main/resources/boost/skills/laravel-query-builder/SKILL.md

Implements the Sort interface to create a custom sort that orders by follower count. The __invoke method receives the query builder, sort direction, and property name.

```php
use Spatie\QueryBuilder\Sorts\Sort;
use Illuminate\Database\Eloquent\Builder;
use Spatie\QueryBuilder\Enums\SortDirection;

class SortMostPopular implements Sort
{
    public function __invoke(Builder $query, SortDirection $direction, string $property): void
    {
        $query->withCount('followers')->orderBy('followers_count', $direction->value);
    }
}
```

--------------------------------

### Wildcard removal: before and after allowedFilters

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

Shows the change from wildcard '*' to explicit filter names. The wildcard parameter is removed in v7.

```php
// Before
QueryBuilder::for(User::class)->allowedFilters('*');
```

```php
// After
QueryBuilder::for(User::class)->allowedFilters('name', 'email');
```

--------------------------------

### Include related model exists with AllowedInclude::exists

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Allows requesting the existence of related models via the postsExists and friendsExists includes. The posts include also allows postsCount and postsExists by default. The result contains posts_exists and friends_exists properties.

```php
// GET /users?include=postsExists,friendsExists

$users = QueryBuilder::for(User::class)
    ->allowedIncludes(
        'posts', // allows including `posts` or `postsCount` or `postsExists`
        AllowedInclude::exists('friendsExists'), // only allows include the existence of `friends()` related models
    );
// every user in $users will contain a `posts_exists` and `friends_exists` property
```

--------------------------------

### Replace request()->appends() with QueryBuilderRequest::fromRequest()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the request macro request()->appends() is replaced by QueryBuilderRequest::fromRequest($request)->appends(). The method takes no arguments.

```php
request()->appends() -> QueryBuilderRequest::fromRequest($request)->appends()
```

--------------------------------

### Multiple default sorts

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/sorting.md

Defines multiple default sorts: first by street descending, then by name ascending. All sorts must be allowed.

```php
// GET /users
$users = QueryBuilder::for(User::class)
    ->defaultSort('-street', 'name')
    ->allowedSorts('name', 'street')
    ->get();

// Will retrieve the users sorted descendingly by street than in ascending order by name
```

--------------------------------

### Pass sort class instance to AllowedSort::custom()

Source: https://github.com/spatie/laravel-query-builder/blob/main/UPGRADING.md

In v2, the second argument for AllowedSort::custom() must be an instance of a sort class, not a classname. Use new MySort() instead of MySort::class.

```php
AllowedSort::custom('name', MySort::class) -> AllowedSort::custom('name', new MySort())
```

--------------------------------

### Nested relationships with dot notation

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Loads nested relationships using dot notation, e.g., `posts.comments`. The `allowedIncludes()` method accepts the nested relationship string.

```php
// GET /users?include=posts.comments,permissions

$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts.comments', 'permissions')
    ->get();

// $users will contain all users with their posts, comments on their posts and permissions loaded
```

--------------------------------

### Define a callback include with AllowedInclude::callback

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/including-relationships.md

Use AllowedInclude::callback to define a tiny custom include. The closure receives the query Builder and can add custom constraints, such as latestOfMany(). This is useful for simple includes without creating a dedicated include class.

```php
QueryBuilder::for(User::class)
    ->allowedIncludes(
        AllowedInclude::callback('latest_post', function (Builder $query) {
            $query->latestOfMany();
        }),
    );
```

--------------------------------

### Custom sort class implementing Sort interface

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/sorting.md

Defines a custom sort class StringLengthSort that implements the Sort interface. The __invoke method orders by the length of the given column.

```php
/**
 * @implements \Spatie\QueryBuilder\Sorts\Sort<\Illuminate\Database\Eloquent\Model>
 */
class StringLengthSort implements \Spatie\QueryBuilder\Sorts\Sort
{
    public function __invoke(Builder $query, bool $descending, string $property)
    {
        $direction = $descending ? 'DESC' : 'ASC';

        $query->orderByRaw("LENGTH(`{$property}`) {$direction}");
    }
}
```

--------------------------------

### Set default filter values

Source: https://github.com/spatie/laravel-query-builder/blob/main/docs/features/filtering.md

Use the default() method to set a default value for a filter when it is not present in the request. Useful for boolean filters.

```php
QueryBuilder::for(User::class)
    ->allowedFilters(
        AllowedFilter::exact('name')->default('Joe'),
        AllowedFilter::scope('deleted')->default(false),
        AllowedFilter::scope('permission')->default(null),
    )
    ->get();
```
Tokens:
Raw