Value Objects

When to use

• The user wraps a primitive (money, email, coordinate) in an immutable type with invariants.
• The user needs two domain values to be considered equal when their contents match, not their identity.
• The user passes bare strings or ints for domain concepts and wants a dedicated type to stop mix-ups.

When NOT to use

• Do not model something with a distinct identity and mutable lifecycle (a User, an Order) as a value object.
• Do not build a value object when the value is simply one of a small closed set of named options.

Core guidance

• Use readonly properties for immutability — Declare the object's properties readonly (PHP 8.1+) and set them only in the constructor, so the value cannot change after creation.
• Enforce invariants in the constructor — Validate every invariant in the constructor and throw on violation, so an instance can never exist in an invalid state.

Quick recipe

1. Declare the fields as promoted readonly constructor parameters, e.g. public function __construct(public readonly int $amountCents, public readonly string $currency) {}. (verify: The property cannot be reassigned after construction)
2. In the constructor, check each invariant and throw InvalidArgumentException on violation (e.g. reject a negative amount or an empty currency code). (verify: Constructing with invalid data throws, never returns a bad instance)
3. Add an equals(self $other): bool method comparing the fields, and with*() methods that return new instances for any change. (verify: Two objects with equal fields report equal; with*() leaves the original unchanged)

Best practices

• Expose an equals(self $other): bool method that compares the meaningful fields, rather than relying on === identity comparison
• Scope each value object to one concept and give it the behavior that belongs to that concept (formatting, arithmetic, comparison) instead of leaking logic to callers
• Add static named constructors (e.g
• Model changes as with*() methods that return a new instance with the changed field, never as setters that mutate the current object

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Storing money as a float — Backing a Money value object with a float leads to rounding errors in arithmetic and comparison. Fix: Store money as integer minor units (cents) plus a currency, and do arithmetic on the integer.
2. Using === to compare value objects — Comparing two value objects with === tests object identity, so equal contents can compare as not equal. Fix: Add and use an equals(self $other): bool method (or == on identical shapes) to compare by value.
3. Mutating a readonly property when cloning — Assigning to a readonly property outside its declaring scope — including inside __clone() on PHP 8.1/8.2 — throws an Error. Fix: Build changed copies with with*() methods that construct a fresh instance; on PHP 8.3+, reinitialize readonly properties inside __clone() if you need clone-based copies.

Version notes

• Readonly properties added in PHP 8.1 (PHP >=8.1) — readonly properties, which value objects use for immutability, are available from PHP 8.1; combine them with constructor property promotion for concise definitions.
• Readonly classes added in PHP 8.2 (PHP >=8.2) — From PHP 8.2 a whole class can be marked readonly, making every property readonly automatically — a natural fit for value objects.
• Reinitializing readonly properties on clone in PHP 8.3 (PHP >=8.3) — From PHP 8.3, __clone() may reinitialize readonly properties, enabling clone-based with*() copies that were impossible on 8.1 and 8.2.

Security

• Let the value object reject untrusted input — Construct value objects from untrusted input at the trust boundary so their constructor rejects malformed data (bad email, out-of-range coordinate) before it reaches the domain.

Testing

• Activation and decision behavior are verified in eval/scenarios/php/value-objects.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: ai-rules/strategy-readonly-immutability, architecture/hexagonal, architecture/repository-pattern, php/enums, php/readonly-properties, psr/psr7-http-messages