Installation & setup

You can install the package via composer:

composer require spatie/laravel-query-builder

The package will automatically register its service provider.

You can optionally publish the config file with:

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

These are the contents of the default config file that will be published:

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,
];