Skip to content
Antares

Response DTOs

A Response DTO is a typed object that represents what you send back to the client. Instead of building arrays by hand, you return a class and Antares serializes it to JSON — applying field renaming, hiding internal properties, and computing derived values along the way.


Annotate a readonly class with #[ResponseDto]:

use Antares\Serialization\Attributes\ResponseDto;
#[ResponseDto]
readonly class UserResponse
{
public function __construct(
public int $id,
public string $name,
public string $email,
) {}
}

Return it from a controller method:

#[Get('/users/{id}')]
public function show(int $id): UserResponse
{
return new UserResponse(id: $id, name: 'John', email: 'john@example.com');
}

The client receives:

{
"id": 1,
"name": "John",
"email": "john@example.com"
}

Use #[Hide] to exclude a property from the serialized output. Useful for internal fields that should never leave the server:

#[ResponseDto]
readonly class UserResponse
{
public function __construct(
public int $id,
public string $name,
#[Hide]
public string $passwordHash,
#[Hide]
public string $internalNotes,
) {}
}

Use #[SerializeAs('key')] to output a property under a different name:

use Antares\Serialization\Attributes\SerializeAs;
#[ResponseDto]
readonly class PostResponse
{
public function __construct(
public int $id,
public string $title,
#[SerializeAs('author_id')]
public int $userId,
#[SerializeAs('published_at')]
public string $createdAt,
) {}
}
{
"id": 1,
"title": "Hello World",
"author_id": 42,
"published_at": "2024-01-15 10:30:00"
}

Use #[Computed] on a public method to include its return value as a field in the response. The method name becomes the key: a leading get is removed (getFullName() becomes fullName), then the DTO’s case setting is applied. #[SerializeAs] doesn’t apply to computed fields:

use Antares\Serialization\Attributes\Computed;
#[ResponseDto]
readonly class PostResponse
{
public function __construct(
public int $id,
public string $title,
public string $body,
) {}
#[Computed]
public function excerpt(): string
{
return mb_strimwidth($this->body, 0, 120, '...');
}
}
{
"id": 1,
"title": "Hello World",
"body": "Full body here...",
"excerpt": "Full body here..."
}

By default property names are output in camelCase. Pass a CaseStyle to the case argument of #[ResponseDto] to change this:

use Antares\Serialization\Attributes\ResponseDto;
use Antares\Serialization\CaseStyle;
#[ResponseDto(case: CaseStyle::SnakeCase)]
readonly class UserResponse
{
public function __construct(
public int $id,
public string $firstName,
public int $authorId,
) {}
}
{
"id": 1,
"first_name": "John",
"author_id": 42
}
CaseStylefirstName becomes
CaseStyle::CamelCase (default)firstName
CaseStyle::SnakeCasefirst_name
CaseStyle::PascalCaseFirstName
CaseStyle::KebabCasefirst-name

#[SerializeAs] always takes precedence over the case setting for any specific field.


A property holding another #[ResponseDto] object is serialized recursively, using that class’s own case setting. Arrays are walked too, so an array of response DTOs becomes an array of JSON objects:

#[ResponseDto(case: CaseStyle::SnakeCase)]
readonly class OrderResponse
{
public function __construct(
public int $id,
public CustomerResponse $customer, // serialized with CustomerResponse's rules
/** @var LineItemResponse[] */
public array $lineItems, // each item serialized
) {}
}

Other values are left to json_encode: scalars, null and arrays are output as they are. A plain object without #[ResponseDto], such as a DateTimeImmutable, is not converted; json_encode outputs its public properties. Format dates as strings before putting them in the DTO.


  • Every property of the object, including private, protected and properties not declared in the constructor, unless it has #[Hide]. null values are included as null.
  • Every method marked #[Computed].
  • The controller must return an object with #[ResponseDto]; returning any other object fails with 500.

The OpenAPI schema is built from constructor parameters only, so declare all output fields in the constructor to keep the docs and the real output in sync.


use Antares\Serialization\Attributes\ResponseDto;
use Antares\Serialization\Attributes\Hide;
use Antares\Serialization\Attributes\SerializeAs;
use Antares\Serialization\Attributes\Computed;
use Antares\Serialization\CaseStyle;
#[ResponseDto(case: CaseStyle::SnakeCase)]
readonly class ArticleResponse
{
public function __construct(
public int $id,
public string $title,
public string $body,
public string $status,
#[SerializeAs('author_id')]
public int $userId,
#[Hide]
public string $internalNotes,
#[SerializeAs('created')]
public string $createdAt,
) {}
#[Computed]
public function excerpt(): string
{
return mb_strimwidth($this->body, 0, 120, '...');
}
}
{
"id": 1,
"title": "Hello World",
"body": "Full article body here...",
"status": "published",
"author_id": 42,
"created": "2024-01-15 10:30:00",
"excerpt": "Full article body here..."
}

internalNotes is hidden. userId is renamed to author_id via #[SerializeAs]. createdAt is renamed to created via #[SerializeAs]. excerpt is computed on the fly.