Strategy — Readonly and Immutability

When to use

• The task models a value or domain concept — money, a date range, coordinates — as an object whose identity is defined by its contents.
• The task is to fix or refactor a mutable object whose in-place changes are causing hard-to-trace bugs across callers.
• The state will be passed around and shared among multiple callers or components that should not surprise one another with mutations.

When NOT to use

• Do not force immutability on a measured hot path where copying a large structure on each change is a real bottleneck and in-place mutation is justified.
• Do not insist on immutability for a short-lived local variable used purely to accumulate a result inside one function before returning.

Core guidance

• Construct fully-formed, valid objects — Require all invariants to be satisfied in the constructor so the object is valid from birth and never passes through a partially-built, invalid state.
• Defensively copy mutable inputs and outputs — When a value object holds a mutable collection or object, copy it on the way in and on the way out so external references cannot mutate the internal state.
• Make value-object fields readonly — Declare a value object's fields as readonly and set them once in the constructor, so no code can change them after construction.
• Confine any needed mutability to a small scope — When mutation is genuinely needed, confine it to a small local scope and produce an immutable result before the value escapes that scope.
• Return a new copy from with-style methods — Model a change as a method that returns a new instance with the field updated, leaving the original untouched, rather than a setter that mutates in place.

Never

• Never make a value object's state publicly mutable or share a mutable object across callers when an immutable copy would serve the same purpose.

Prefer

• Prefer building fully-formed immutable value objects with readonly fields, and return a modified copy rather than mutating an existing instance in place.

Avoid

• Avoid adding setters or in-place mutators to value objects; expose with-style methods that return a new instance with the change applied instead.

Escalate to user when

• Escalate to the user when a design seems to genuinely need shared mutable state — such as a large in-place buffer for performance — and confirm the trade-off before giving up immutability.

Quick recipe

1. Declare the fields readonly, set them all in a constructor that enforces the invariants, and copy any mutable inputs defensively. (verify: Every field is readonly, the constructor rejects invalid input, and no mutable input is stored by reference.)
2. Replace any setter with a with-style method that returns a new instance carrying the change, and return copies or immutable views of internal collections. (verify: No setter mutates the object in place, each change returns a new instance, and no method leaks a mutable reference to internal state.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Ignoring the return of a with-style method — Calling a with-style method and discarding its return value leaves the original unchanged, so the intended update is silently lost. Fix: Assign the result of every with-style call back to a variable and use that new instance from then on.
2. Returning the internal collection breaks immutability — Returning the object's internal mutable array or collection lets the caller change the object's state from the outside. Fix: Return a copy or an immutable view of the collection so external code cannot mutate the internal state.
3. A shared mutable object mutated through an alias — Passing a mutable object to several holders lets one of them mutate it and change what all the others see. Fix: Make the object immutable, or hand each holder a defensive copy, so no holder can affect another.

Version notes

• Immutability discipline is version-agnostic (PHP >=7.4) — Preferring immutable value objects over mutable shared state is a strategy that applies to any PHP version; it constrains how the agent shapes state, not which language features it uses, so it holds from PHP 7.4 upward even where the readonly keyword is emulated by convention.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-readonly-immutability.yaml.

Additional resources

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

Knowledge graph

Related: ai-rules/strategy-minimal-diff, php/readonly-properties, php/value-objects