Skip to content
Antares

DTOs

A DTO (Data Transfer Object) is how Antares models an incoming request body. You define a class, mark it with #[Dto], add validation rules to its constructor parameters, and Antares handles the rest: decoding the body, mapping fields, validating, and injecting the populated object into your controller.

If anything fails, an error response is returned automatically and your controller method is never called.


use Antares\Validation\Attributes\Dto;
use Antares\Validation\Attributes\NotBlank;
use Antares\Validation\Attributes\Email;
use Antares\Validation\Attributes\MinLength;
#[Dto]
readonly class CreateUserRequest
{
public function __construct(
#[NotBlank]
#[MinLength(2)]
public string $name,
#[NotBlank]
#[Email]
public string $email,
) {}
}

Declare the fields as promoted constructor parameters: hydration, validation and the OpenAPI schema all read the constructor. readonly is recommended but not required.

Use it in a controller by type-hinting it as a parameter:

#[Post('/users', 201)]
public function store(CreateUserRequest $request): UserResponse
{
return new UserResponse(id: 1, name: $request->name, email: $request->email);
}
Request Content-TypeDTO is filled from
application/x-www-form-urlencoded or multipart/form-dataThe parsed form fields
Anything elseThe body decoded as JSON. An empty body counts as {}

A body that isn’t valid JSON is rejected with 400 Invalid JSON body., and valid JSON that isn’t an object (a string, number or null) with 400 Request body must be a JSON object.

There are two kinds of failure, with different status codes:

The data doesn’t fit the DTO (400). A required field is missing, a value has the wrong shape ("abc" for an int, an array for a string, a string for a nested DTO, null for a non-nullable field), or a #[Strict] DTO receives an unknown field. The response reports the first problem:

{
"type": "https://antares.dev/errors",
"title": "Missing required parameter: email",
"status": 400
}

The data breaks a validation rule (422). Every failed rule is reported, per field:

{
"type": "https://antares.dev/errors",
"title": "Validation failed",
"status": 422,
"errors": {
"name": ["The value must be at least 2 characters long."],
"email": ["The value must be a valid email address."]
}
}

See DTOs & Hydration for exactly how each field type is filled and cast.


Parameters with defaults are optional in the request body. Nullable parameters without a default are optional too, and become null:

#[Dto]
readonly class UpdateProfileRequest
{
public function __construct(
public ?string $nickname, // optional, null if missing
#[In(['asc', 'desc'])]
public string $order = 'asc', // optional, 'asc' if missing
) {}
}

DTOs can nest other DTOs. The hydrator recurses into them automatically:

#[Dto]
readonly class AddressRequest
{
public function __construct(
#[NotBlank] public string $street,
#[NotBlank] public string $city,
#[NotBlank] public string $country,
) {}
}
#[Dto]
readonly class CreateOrderRequest
{
public function __construct(
#[NotBlank] public string $sku,
#[Min(1)] public int $quantity,
public AddressRequest $address,
) {}
}
{
"sku": "WIDGET-42",
"quantity": 3,
"address": {
"street": "123 Main St",
"city": "Athens",
"country": "GR"
}
}

A nested DTO is validated before its parent. If it fails, the errors map uses the nested field names ("street", not "address.street"), and the parent’s own rules are not checked in that response. Arrays of DTOs are not supported yet.


By default unknown fields in the request body are ignored. Add #[Strict] to reject them with 400 Bad Request:

#[Dto]
#[Strict]
readonly class CreateUserRequest
{
public function __construct(
public string $name,
public string $email,
) {}
}

Sending "name": "John", "email": "john@example.com", "role": "admin" returns 400 with Unknown fields: role.


See Validation Attributes for every built-in rule and exactly what it checks, and Custom Rules to write your own.