Errors

Every problem of the request is reported at once with MyProgs\QueryBuilder\Exceptions\InvalidQueryParameters. It extends Laravel's ValidationException, so the client gets the usual 422 response:

GET /users?filter[age]=3&filter[posts.views][gte]=abc&sort=email

{
    "message": "Filter [age] is not allowed; allowed: name, active, created_at, posts.views, posts.status. (and 2 more errors)",
    "errors": {
        "filter.age": ["Filter [age] is not allowed; allowed: name, active, created_at, posts.views, posts.status."],
        "filter.posts.views": ["Filter [posts.views] operator [gte] expects an integer, got [abc]."],
        "sort": ["Requested sort `email` is not allowed. Allowed sorts are `name`, `created_at`, `country`, `postsCount`."]
    }
}

Error codes

$exception->details holds the same errors as QueryError objects with a parameter, a code and the allowed values. Render them in your exception handler if the client needs machine-readable codes:

{ "parameter": "filter.age", "code": "unknown_filter", "message": "...", "allowed": ["name", "active", "created_at", "posts.views", "posts.status"] }

The codes are the cases of QueryErrorCode:

Code	Meaning
unknown_filter	the filter is not allowed
unknown_sort	the sort is not allowed
unknown_include	the include is not allowed
unknown_field	the field is not allowed
unknown_append	append is not supported
unknown_operator	there is no such operator
operator_not_allowed	the filter does not allow the operator
invalid_value	the value does not fit the filter type
invalid_arity	wrong number of values (between needs two)
ambiguous_fields	one path is reached by two fields keys
invalid_page	page or per_page out of range
nulls_not_allowed	a :nulls-* suffix on a sort without clientNulls()

An unknown_include lists the includes allowed where the request went wrong: the first level for include=foo, those under posts for include=posts.foo.

A malformed parameter (an array where a string is expected) is a 400 MalformedQueryParameter, as in the spatie-compatible API.

Translations

The messages follow the application locale (App::setLocale(), the locale and fallback_locale keys of config/app.php). The package ships English and Russian, and a locale it has no translation for gets the fallback one (English when the fallback has none either). The codes, parameters and allowed values are the same in every language.

The (and 2 more errors) suffix of message comes from Laravel itself; it is translated by the lang/<locale>.json of the application.

To change the wording or add a language, publish the translations to lang/vendor/query-builder and edit them there:

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

Only the definitions API is translated: the exception messages of the spatie-compatible API (InvalidFilterQuery and the others) stay in English, as in spatie.

Mistakes in a definition

A mistake in a definition itself (an unknown operator for a type, a relation sort without a column, a morphTo path without types) throws InvalidArgumentException. It is a bug in your code, not in the request.