Skip to content
Antares

DTOs & Hydration

Mark a class with #[Dto] and declare its fields as constructor parameters, with validation attributes on them. readonly is recommended but not required:

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

Validation rules are read from constructor parameters, so use promoted properties (public string $name in the constructor).

$data = ['name' => 'John', 'email' => 'john@example.com'];
$dto = $hydrator->hydrate(CreateUserRequest::class, $data);
$dto->name; // 'John'
$dto->email; // 'john@example.com'
$dto->role; // 'viewer' (default)

For each constructor parameter, the Hydrator looks up the key with the same name in the data:

SituationResult
Key missing, parameter has a defaultThe default is used
Key missing, parameter is nullablenull
Key missing otherwiseHydrationException: Missing required parameter: name
Value is nullnull if the parameter is nullable, otherwise HydrationException: Parameter name must not be null.
int / floatThe value must pass PHP’s integer / float check ("42" is accepted and becomes 42), otherwise HydrationException
boolThe value must be a recognisable boolean: true/false, 1/0, "true"/"false", "yes"/"no", "on"/"off", otherwise HydrationException
stringA string, or a number (cast to string). Arrays, objects and booleans are rejected with HydrationException
A class marked #[Dto]Hydrated recursively; the value must be an object (array), otherwise HydrationException
arrayMust be an array, otherwise HydrationException
Untyped, mixed, or union typesPassed through unchanged

A parameter typed as a class without #[Dto] (e.g. DateTimeImmutable), or a DTO class without a constructor, is a mistake in the DTO itself rather than in the request. It throws a LogicException, which the framework turns into a hidden 500 and logs.

Unknown keys are ignored, unless the DTO has #[Strict].

Add #[Strict] to reject any field the DTO doesn’t declare. The request fails with a HydrationException (400) listing the unknown fields:

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

Sending {"name": "John", "email": "john@example.com", "role": "admin"} fails with Unknown fields: role. #[Strict] does not change how values are cast.

A parameter typed as another #[Dto] class is hydrated from the nested array:

#[Dto]
readonly class AddressRequest
{
public function __construct(
#[NotBlank] public string $street,
#[NotBlank] public string $city,
) {}
}
#[Dto]
readonly class CreateOrderRequest
{
public function __construct(
#[NotBlank] public string $sku,
public AddressRequest $address,
) {}
}

The nested DTO is validated as soon as it is built, before its parent. If it fails, its errors are reported under the nested field names ({"street": [...]}, not address.street), and the parent’s own rules are not checked in that run.

An array parameter is passed through as-is. Use #[ArrayOf('string')] (or 'int', 'float', 'bool', 'array') to check the items’ types. Arrays of DTOs are not hydrated: #[ArrayOf(ItemRequest::class)] expects objects, but the request contains plain arrays, so it will always fail.