> For the complete documentation index, see [llms.txt](https://docs.opensoutheners.com/oss/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opensoutheners.com/oss/laravel-apiable/request-features/validation.md).

# Query Param Validation

Validate incoming query parameters against your allowed definitions.

By default, Laravel Apiable silently ignores query parameters that are not in the allowed list. Unrecognised filters are skipped, unknown sorts are dropped, and so on. This is intentional — it makes your API more permissive during development and avoids breaking clients that send extra parameters.

When you want stricter behaviour, you can enable parameter validation to reject any parameter that does not match your allowed definitions.

## Enabling validation

Set `requests.validate_params` to `true` in `config/apiable.php`:

```php
'requests' => [
    'validate_params' => true,
    // ...
],
```

With validation enabled, any query parameter that does not match an allowed definition causes the package to throw an exception, which results in an error response to the client.

## What is validated

The `QueryParamsValidator` class is used internally for every request feature. When `validate_params` is `true`, it enforces:

| Feature        | Rejection condition                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Filters        | Attribute not in `allowedFilters`, operator not allowed for that attribute, or value not in the restricted set                |
| Sorts          | Attribute not in `allowedSorts`, or direction not permitted (e.g. sending `?sort=-title` when only `ASCENDANT` is configured) |
| Includes       | Relationship not in `allowedIncludes`                                                                                         |
| Fields         | Resource type not in `allowedFields`, or column not in the allowed list for that type                                         |
| Appends        | Resource type not in `allowedAppends`, or accessor not in the allowed list for that type                                      |
| Search filters | Attribute not in `allowedSearchFilters`, or value not in the restricted set                                                   |

## Error response

When a filter, include, field, append, or search filter parameter fails validation, the package throws a `Symfony\Component\HttpKernel\Exception\HttpException` with a `400` status code and a message describing the rejected parameter, for example:

```
"title" is not filterable or contains invalid values
"comments" cannot be included
"nonexistent" fields for resource type "post" cannot be sparsed
```

Because it's an `HttpException`, no extra exception-handler wiring is required — register [`Apiable::jsonApiRenderable()`](/oss/laravel-apiable/error-handling/error-handling.md) as usual and the `400` status and message are forwarded to the client automatically as a JSON:API error object.

```php
// bootstrap/app.php
use Illuminate\Foundation\Configuration\Exceptions;
use OpenSoutheners\LaravelApiable\Support\Facades\Apiable;
use Throwable;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->renderable(function (Throwable $e, $request) {
        if ($request->is('api/*') && app()->bound('apiable')) {
            return Apiable::jsonApiRenderable($e);
        }
    });
})
```

## `QueryParamsValidator` internals

The `QueryParamsValidator` class is used by the `AllowsFilters`, `AllowsSorts`, `AllowsIncludes`, `AllowsFields`, `AllowsAppends`, and `AllowsSearch` traits. Each trait passes its params and rules to the validator, which runs a chain of condition callbacks.

When `validate_params` is `false`, failed conditions are silently skipped and only matching parameters are returned. When `validate_params` is `true`, a failed condition calls the associated exception handler instead.

You can check at runtime whether validation is enforced:

```php
/** @var \OpenSoutheners\LaravelApiable\Http\RequestQueryObject $requestQueryObject */
$requestQueryObject->enforcesValidation(); // bool
```

{% hint style="info" %}
Validation is applied per-feature independently. You can have strict filter validation while sorts remain permissive if you configure your `allowedSorts` broadly. The config flag is global, but the rules you declare determine what passes.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opensoutheners.com/oss/laravel-apiable/request-features/validation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.