laravel.pw

English

Русский

English

Русский

Appearance

Installation and configuration ​

Installation ​

bash
composer require myprogs/query-builder

The service provider is discovered automatically. The package needs PHP 8.3 or newer and Laravel 12 or 13.

Configuration ​

The defaults work without a config file. Publish it when you need to change parameter names, the delimiter or how unknown parameters are treated:

bash
php artisan vendor:publish --tag=query-builder-config

The file is config/query-builder.php. It is also published under the tag that spatie/laravel-query-builder documents, so existing scripts keep working:

bash
php artisan vendor:publish --tag=laravel-query-builder-config

Parameter names ​

php
'parameters' => [
    'include' => 'include',
    'filter' => 'filter',
    'sort' => 'sort',
    'fields' => 'fields',
    'append' => 'append',
],

The names of the query string parameters. Change them when your API already uses other names, for example 'filter' => 'where' for ?where[name]=john.

Delimiter ​

php
'delimiter' => ',',
'filter_value_splitting_enabled' => true,

The separator of multi-value parameters: filter[id]=1,2,3, sort=-created_at,name, include=posts,comments. With filter_value_splitting_enabled set to false, filter values are not split and filter[name]=Smith, John is one value. A single filter can use its own delimiter, see Filtering.

Aggregate suffixes ​

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

The suffixes that turn a relation name into an aggregate include: include=postsCount, include=postsExists. See Including relations.

Unknown parameters ​

php
'disable_invalid_filter_query_exception' => false,
'disable_invalid_sort_query_exception' => false,
'disable_invalid_include_query_exception' => false,

By default a filter, sort or include that the endpoint does not allow throws an exception (a 400 response). Set a key to true to ignore such parameters silently. These keys apply to the spatie-compatible API; the definitions API always reports unknown parameters.

Field names ​

php
'convert_relation_names_to_snake_case_plural' => true,
'convert_relation_table_name_strategy' => null,
'convert_field_names_to_snake_case' => false,

How fields[...] keys and names are matched:

  • convert_relation_names_to_snake_case_plural: a relation is keyed by its name in snake case and plural, include=userOwner&fields[user_owners]=id. With false, by the name as written in include: fields[userOwner]=id.
  • convert_relation_table_name_strategy: key a relation by the table of the related model instead, converted with snake_case, camelCase or none. null turns it off.
  • convert_field_names_to_snake_case: convert requested field names, so firstName selects first_name.

See Selecting fields.

Translations ​

The error messages of the definitions API are translated into English and Russian and follow the application locale. To change the wording or add a language, publish the translations to lang/vendor/query-builder:

bash
php artisan vendor:publish --tag=query-builder-translations

See Errors.