Readonly Properties (PHP 8.1)

Also Known As

TL;DR

Explanation

Readonly properties (PHP 8.1) must be typed and can only be written once — either in the constructor or at the point of declaration. Any subsequent write throws an Error. This is ideal for value objects and DTOs where properties should never change after construction. PHP 8.2 added readonly classes, where all promoted and explicitly declared properties become readonly automatically. Readonly properties cannot have a default value in their declaration (only in the constructor).

Common Misconception

Why It Matters

Common Mistakes

• Trying to reassign a readonly property even in the same class — any write after initialisation throws an Error.
• Not using constructor promotion with readonly — the combination is the primary intended usage.
• Using readonly on properties that need cloning with modifications — use a wither method returning a new instance.
• Declaring readonly on static properties — not supported; readonly applies to instance properties only.

Code Examples

// Mutable value object — can be corrupted after construction:
class Money {
    public float $amount;
    public string $currency;
}
$price = new Money();
$price->amount = 9.99;
$price->amount = -999; // Nothing prevents this mutation

// Readonly — immutable by language enforcement:
class Money {
    public function __construct(
        public readonly float $amount,
        public readonly string $currency,
    ) {}
}

// PHP 8.1 — individual readonly properties
class User {
    public function __construct(
        public readonly int    $id,
        public readonly string $email,
    ) {}
    // $user->id = 99; → Error: Cannot modify readonly property
}

// PHP 8.2 — readonly class (all promoted properties are readonly)
readonly class Money {
    public function __construct(
        public int    $amount,
        public string $currency,
    ) {}

    // Methods can still return new instances
    public function add(self $other): self {
        return new self($this->amount + $other->amount, $this->currency);
    }
}

References

• ↗ https://www.php.net/manual/en/language.oop5.properties.php#language.oop5.properties.readonly-properties

Tags

Related Terms