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.
Defining a DTO
Section titled “Defining a DTO”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);}Where the Data Comes From
Section titled “Where the Data Comes From”Request Content-Type | DTO is filled from |
|---|---|
application/x-www-form-urlencoded or multipart/form-data | The parsed form fields |
| Anything else | The 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.
What Happens When It Fails
Section titled “What Happens When It Fails”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.
Default Values
Section titled “Default Values”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 ) {}}Nested DTOs
Section titled “Nested DTOs”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.
Strict Mode
Section titled “Strict Mode”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.
Validation Rules
Section titled “Validation Rules”See Validation Attributes for every built-in rule and exactly what it checks, and Custom Rules to write your own.