Request Validation

The RequestValidationMiddleware is a core component of Apivalk’s Documentation-Driven Development approach. It ensures that every request hitting your controller strictly adheres to the schema defined in your ApivalkRequestDocumentation.

How it Works

The middleware intercepts the request before it reaches the controller and performs the following steps:

1. Extract Runtime Documentation: It retrieves the merged documentation from $request->getRuntimeDocumentation() — the developer-declared properties plus route-derived metadata (filters, pagination params, available sort fields).
2. Property Validation: It iterates Body, Query, and Path properties and checks each corresponding value in the ParameterBag — running all validators attached to the property (StringValidator, IntegerValidator, EnumValidator, …).
3. Required Field Check: If a property is marked required but missing, a validation error is recorded.
4. Filter Validation: Each filter in $request->filtering() is validated against its underlying property (required / type / custom validators).
5. Sort Field Validation: Each Sort in $request->sorting() must correspond to a field declared on the route via Route::sorting([...]). Unknown fields sent via ?order_by=... produce a validation error (key order_by, message Invalid sort field "X"). Routes without declared sortings skip this check.
6. Error Collection: All errors are collected into ValidationErrorObject[].

Automatic Response

If one or more validation errors are found, the middleware short-circuits the request lifecycle. It does not call the next middleware or the controller. Instead, it immediately returns a BadValidationApivalkResponse (HTTP 422 Unprocessable Entity).

Example Error Response

{
    "status": "error",
    "message": "Validation failed",
    "errors": [
        {
            "property": "email",
            "message": "Value is not a valid email address"
        },
        {
            "property": "age",
            "message": "Field is required"
        }
    ]
}

Benefits

• Clean Controllers: Your controllers never need to contain validation logic. By the time they are executed, you are guaranteed that the input is valid and correctly typed.
• Consistency: Validation errors follow a standardized format across your entire API.
• Synchronized Docs: Since validation is driven by the documentation, your API’s behavior always matches what is described in your generated OpenAPI specification.

Usage

Enable the middleware in your configuration:

use apivalk\apivalk\Middleware\RequestValidationMiddleware;

$configuration->addMiddleware(new RequestValidationMiddleware());