PHP DTOs and Value Objects with Readonly Classes

In modern PHP applications, especially those following Domain-Driven Design or clean architecture, you often need to transfer data between layers or represent immutable concepts. Two patterns that help are Data Transfer Objects (DTOs) and Value Objects. DTOs are simple containers that move data between processes, like from a controller to a service or from an API to a client. They typically have no behavior. Value Objects, on the other hand, are immutable objects that represent a descriptive aspect of your domain, such as an Email, Money, or a Coordinate. They encapsulate logic and ensure validity.

PHP 8.1 introduced readonly properties and readonly classes, which make implementing these patterns much cleaner. A readonly class ensures all properties are readonly, meaning they can only be set once, typically in the constructor. This enforces immutability at the language level, reducing bugs and making your code easier to reason about.

In this tutorial, you'll learn how to create DTOs and Value Objects using readonly classes, with practical examples. We'll cover constructor promotion, named arguments, and how to handle serialization. You'll also see common pitfalls, debugging strategies, and production incidents. By the end, you'll be able to confidently use these patterns to write safer, more maintainable PHP code.

What are DTOs and Value Objects?

Data Transfer Objects (DTOs) are simple objects that carry data between processes. They have no behavior, only properties and maybe getters. Their purpose is to transfer data, often across boundaries like HTTP requests, database queries, or service layers. Value Objects, on the other hand, are immutable objects that represent a concept in your domain. They have equality based on their properties, not identity. For example, two Email objects with the same address are considered equal. Value Objects often contain validation logic to ensure they are always in a valid state.

In PHP, before readonly classes, you had to manually write getters and avoid setters to achieve immutability. With readonly classes, you can simply declare the class as readonly, and all properties become readonly automatically. This reduces boilerplate and enforces immutability at the language level.

Let's start with a simple DTO example: a UserDTO that transfers user data from an API to your application.

<?php

readonly class UserDTO
{
    public function __construct(
        public int $id,
        public string $name,
        public string $email,
    ) {}
}

// Usage:
$userDTO = new UserDTO(id: 1, name: 'Alice', email: 'alice@example.com');
echo $userDTO->name; // Alice

Creating Value Objects with Readonly Classes

Value Objects are more than just data carriers; they encapsulate domain logic. For example, an Email value object should validate the email format and provide methods to access parts of the email. With readonly classes, you can ensure that once created, the email cannot be changed.

Here's an example of a Value Object for an email address:

<?php

readonly class Email
{
    public string $localPart;
    public string $domain;

    public function __construct(
        public string $value
    ) {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Invalid email address');
        }
        [$local, $domain] = explode('@', $value);
        $this->localPart = $local;
        $this->domain = $domain;
    }

    public function __equals(object $other): bool
    {
        return $other instanceof self && $this->value === $other->value;
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

// Usage:
$email = new Email('alice@example.com');
echo $email->domain; // example.com

Working with Collections of DTOs and Value Objects

Often you need to work with lists of DTOs or Value Objects. For example, an API might return a list of users. You can create a collection class that holds an array of DTOs. With readonly classes, you can make the collection immutable as well.

Here's an example of a UserCollection that holds UserDTO objects:

<?php

readonly class UserCollection
{
    /** @var UserDTO[] */
    public array $users;

    public function __construct(UserDTO ...$users)
    {
        $this->users = $users;
    }

    public function count(): int
    {
        return count($this->users);
    }

    public function toArray(): array
    {
        return array_map(fn(UserDTO $user) => [
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email,
        ], $this->users);
    }
}

// Usage:
$collection = new UserCollection(
    new UserDTO(id: 1, name: 'Alice', email: 'alice@example.com'),
    new UserDTO(id: 2, name: 'Bob', email: 'bob@example.com')
);
echo $collection->count(); // 2

Serialization and Deserialization

DTOs and Value Objects often need to be serialized to JSON for API responses or stored in caches. PHP's readonly classes work well with json_encode if properties are public. However, deserialization can be tricky because you cannot set readonly properties after construction. You need to create a new instance from the serialized data.

One approach is to use a named constructor or a static factory method. Here's an example for the Email Value Object:

<?php

readonly class Email
{
    public function __construct(public string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Invalid email');
        }
    }

    public static function fromString(string $value): self
    {
        return new self($value);
    }

    public function __serialize(): array
    {
        return ['value' => $this->value];
    }

    public function __unserialize(array $data): void
    {
        // Cannot modify readonly properties, so we need to reconstruct
        // This method is called after construction, but we can't set $value.
        // Instead, use a workaround: create a new instance via fromString.
        // Actually, __unserialize is called on an already constructed object.
        // To handle this, we can use a different approach: implement Serializable or use a DTO.
        // For simplicity, we'll skip __unserialize and use a factory.
    }
}

// Deserialization workaround:
$data = ['value' => 'alice@example.com'];
$email = Email::fromString($data['value']);

Comparing Value Objects

Value Objects should be compared by their properties, not by reference. PHP's == operator compares objects by properties if the class defines __equals()? Actually, PHP does not have a built-in __equals() magic method. You need to implement your own comparison method. Alternatively, you can use the == operator which compares all properties recursively, but this may not be reliable for nested objects.

A common approach is to implement an equals() method:

<?php

readonly class Email
{
    public function __construct(public string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Invalid email');
        }
    }

    public function equals(Email $other): bool
    {
        return $this->value === $other->value;
    }
}

$email1 = new Email('alice@example.com');
$email2 = new Email('alice@example.com');
var_dump($email1 === $email2); // false (different objects)
var_dump($email1 == $email2); // true (PHP compares properties)
var_dump($email1->equals($email2)); // true (custom method)

Best Practices and Common Pitfalls

When using readonly classes for DTOs and Value Objects, keep these best practices in mind:

1. Keep DTOs simple: They should only contain public properties and no methods (except maybe serialization).
2. Validate in Value Object constructors: Ensure the object is always valid.
3. Avoid inheritance: Readonly classes cannot be extended if they are final. Prefer composition over inheritance.
4. Use named arguments: They make construction clearer and avoid order issues.
5. Be careful with arrays: Readonly classes don't make array contents immutable. Consider using immutable collections.

<?php

// Good DTO: only public properties
readonly class UserDTO
{
    public function __construct(
        public int $id,
        public string $name,
    ) {}
}

// Good Value Object: validation and equality
readonly class Money
{
    public function __construct(
        public int $amount,
        public string $currency
    ) {
        if ($amount < 0) {
            throw new \InvalidArgumentException('Amount cannot be negative');
        }
        if (!in_array($currency, ['USD', 'EUR'])) {
            throw new \InvalidArgumentException('Unsupported currency');
        }
    }

    public function equals(Money $other): bool
    {
        return $this->amount === $other->amount && $this->currency === $other->currency;
    }
}