Building Immutable Objects in PHP with Readonly Properties

Readonly properties in PHP 8.2 can only be assigned once in the constructor or at declaration and cannot be modified afterward, enforcing immutability at the language level. 2. To achieve deep immutability, wrap mutable types like arrays in ArrayObject or use custom immutable collections such as TagCollection that prevent direct state changes. 3. Best practices include initializing all properties in the constructor, avoiding setters, returning new instances via withX() methods, using final classes, and disabling cloning to prevent mutation. 4. Limitations include lack of support for dynamic properties, no deep freezing of objects or arrays, and the need for manual handling of nested mutability. 5. Despite these gotchas, combining readonly properties with value objects and functional patterns enables safe, predictable, and thread-safe immutable objects using only native PHP features, making it easier to build robust domain models without external libraries.

In PHP 8.2, a powerful feature was introduced: readonly properties. This makes it much easier to build immutable objects — objects whose state cannot be changed after creation. Immutable objects are valuable because they’re predictable, thread-safe, and reduce bugs caused by unintended state changes.

Here’s how you can use readonly to create truly immutable value objects in PHP.

What Are Readonly Properties?

A readonly property can only be assigned once — either at the declaration or inside the constructor. After that, it cannot be modified.

class User
{
    public function __construct(
        public readonly string $id,
        public readonly string $email
    ) {}
}

Once set, $user->email = 'new@example.com'; will throw a Cannot modify readonly property error.

This enforces immutability at the language level — no need to rely on conventions or magic methods.

Enforcing Deep Immutability

Using readonly on its own doesn’t guarantee full immutability if your property holds a mutable type like an array or object. For example:

class BlogPost
{
    public function __construct(
        public readonly string $title,
        public readonly array $tags
    ) {}
}

$post = new BlogPost('PHP 8.2', ['php', 'immutable']);
$post->tags[] = 'readonly'; // This works! Array content can still change.

To prevent this, you need to defend against mutation of arrays and objects.

✅ Solution: Wrap arrays in ArrayObject or use immutable collections

class BlogPost
{
    /**
     * @var readonly ArrayObject<int, string>
     */
    public readonly ArrayObject $tags;

    public function __construct(
        public readonly string $title,
        array $tags
    ) {
        $this->tags = new ArrayObject($tags);
        $this->tags->setFlags(ArrayObject::ARRAY_AS_PROPS);
        $this->tags->getFlags() & ~ArrayObject::STD_PROP_LIST;
    }
}

Now you can read $post->tags, but modifying it (e.g., $post->tags[] = 'hack') will fail because the property itself is readonly — you can't reassign it, and if you expose methods to manipulate internal state, you control them explicitly.

Alternatively, consider using value objects for collections:

/**
 * @implements \IteratorAggregate<string>
 */
class TagCollection implements \IteratorAggregate
{
    private array $tags;

    public function __construct(array $tags) {
        $this->tags = array_values(array_unique($tags));
    }

    public function getIterator(): \Traversable
    {
        return new \ArrayIterator($this->tags);
    }

    public function withAdded(string $tag): self
    {
        return new self([...$this->tags, $tag]);
    }
}

class BlogPost
{
    public function __construct(
        public readonly string $title,
        public readonly TagCollection $tags
    ) {}
}

Now immutability is preserved: you can’t modify $post->tags, and even if you iterate it, any changes require creating a new instance.

Best Practices for Immutable Objects

To build robust immutable objects in PHP:

• ✅ Use readonly on all properties
• ✅ Initialize everything in the constructor
• ✅ Avoid public setters or mutator methods
• ✅ Return new instances instead of modifying state
• ✅ Use final classes to prevent unintended overrides
• ✅ Consider using __clone() to prevent accidental mutation via cloning

final class User
{
    public function __construct(
        public readonly string $id,
        public readonly string $name,
        public readonly string $email
    ) {}

    // Instead of setEmail(), return a new instance
    public function withEmail(string $email): self
    {
        return new self($this->id, $this->name, $email);
    }

    // Prevent cloning (optional)
    public function __clone()
    {
        throw new \BadMethodCallException('Cloning is disabled for immutable object.');
    }
}

Usage:

$user = new User('123', 'Alice', 'alice@example.com');
$updated = $user->withEmail('alice@new.com'); // New instance
// $user remains unchanged

Limitations and Gotchas

• readonly only works on class properties — not dynamic properties
• You can’t assign to a readonly property outside the constructor, even from within the class
• Objects and arrays assigned to readonly props aren't deeply frozen — you must handle that yourself
• PHP doesn’t have built-in immutable arrays, so you’ll need wrappers or custom logic

Summary

With readonly in PHP 8.2 , building immutable objects is now practical and safe. Combine readonly properties with defensive copying, value objects, and functional-style methods (withX() instead of setX()) to create clean, predictable domain models.

You don’t need a framework or library — just good design and PHP’s built-in features.

Basically: declare it once, keep it safe.

The above is the detailed content of Building Immutable Objects in PHP with Readonly Properties. For more information, please follow other related articles on the PHP Chinese website!