Unknown parameters & errors

Requesting a filter or sort that is not allow-listed throws UnknownFilter or UnknownSort. Both extend Symfony’s HttpException with a 400 status, so Laravel renders them as a normal HTTP error:

GET /posts?filter[secret]=1

HTTP/1.1 400 Bad Request
{"message": "Requested filter(s) `secret` are not allowed. Allowed filter(s) are `status, title`."}

Ignore mode

Set mode.unknown_filter or mode.unknown_sort to ignore to drop the offending key silently and apply only the allow-listed ones. A sort string that is dropped entirely reads as if it were absent, so defaultSort() still orders the page. Any value other than reject or ignore throws InvalidConfigurationException instead of guessing:

// config/query-builder.php
'mode' => [
    'unknown_filter' => 'ignore',   // drop un-allow-listed filters
    'unknown_sort'   => 'reject',   // keep sorts strict (HTTP 400)
],

Messages & translations

Messages come from query-builder::errors.unknown_filter and query-builder::errors.unknown_sort, with :unknown and :allowed placeholders. The reflected unknown keys are capped — the first 5, each truncated to 64 characters, with an “…and N more” suffix — so attacker-controlled keys cannot flood the response or your logs. Publish the translations to reword them or add a language:

// lang/vendor/query-builder/sk/errors.php
return [
    'unknown_filter' => 'Filtre :unknown nie sú povolené. Povolené filtre: :allowed.',
    'unknown_sort' => 'Triedenia :unknown nie sú povolené. Povolené triedenia: :allowed.',
];

Exception reference

use RoundlyConsulting\QueryBuilder\Exceptions\QueryBuilderException;

try {
    $posts = QueryBuilder::for(Post::class, $request)
        ->allowedFilters('status')
        ->get();                        // filters apply here — lazily
} catch (QueryBuilderException $e) {
    // UnknownFilter / UnknownSort — both carry HTTP status 400
}