CQRS (Command Query Responsibility Segregation)

When to use

• The user wants to represent each state-changing intent as a command object dispatched to a dedicated handler.
• The user wants distinct models for changing state and for reading data because one shared model has become awkward for both.
• The user wants read models tailored to each view, bypassing the write model to return exactly what a screen needs.

When NOT to use

• Do not adopt event sourcing or eventual consistency just because you are separating reads from writes.
• Do not split reads and writes for a plain CRUD screen where one model serves both sides comfortably.

Core guidance

• Make commands change state and return nothing — Let a command express an intent to change state and return void (or only an identifier); never return the queried result of the change from the command handler.
• Make queries return data with no side effects — Let a query return data and change nothing observable; a query handler must never write to the store or mutate domain state.

Quick recipe

1. Define an immutable command carrying the intent's data (e.g. final class RenameCustomer) and a handler whose handle() applies the change and returns void. (verify: The handler mutates state and returns nothing beyond an optional new id)
2. Define a query (e.g. final class CustomerProfile) and a handler returning a view-shaped read model DTO with no side effects. (verify: The query handler only reads and returns data the screen needs)
3. Route commands and queries through a small dispatcher (or the framework's message bus) that maps each message to its single handler, registered at the composition root. (verify: Dispatching a command invokes only its handler; dispatching a query returns its read model)

Best practices

• Route each command or query message to exactly one handler dedicated to it, rather than a service with many mixed methods
• Build read models as flat, view-shaped DTOs that a query returns directly, rather than loading the write-side aggregate and reshaping it in the controller
• Separate the command and query models in code first while both read from the same database; only introduce a separate read store when a measured need justifies it

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. A command handler that returns the read result — Returning the full updated entity from a command handler so the caller can render it merges the write and read responsibilities the split was meant to keep apart. Fix: Return at most a new identifier from the command, then issue a separate query to fetch the read model for display.
2. Surprising staleness from an async read model — Updating the read model asynchronously and then reading it immediately after a command can show stale data, confusing users who expect their change to appear at once. Fix: Keep the read model synchronous until you truly need async, and where it is async, signal the pending state in the UI or read from the write side for the just-changed record.
3. Applying CQRS to every corner of the app — Forcing commands, queries, handlers, and read models onto simple lookups and settings screens buries trivial features under ceremony. Fix: Apply CQRS to the bounded contexts with real read/write asymmetry, and let simple areas keep a plain shared model.

Version notes

• Immutable messages with PHP 8.1 readonly (PHP >=8.1) — PHP 8.1 readonly promoted properties let commands and queries be defined as immutable data carriers in a couple of lines, reinforcing that a message is a fixed request.
• Typed class constants aid message metadata in PHP 8.3 (PHP >=8.3) — From PHP 8.3, typed class constants let a command or read model declare stable metadata (a message name or version) with an enforced type on the message class.

Security

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

Testing

• Activation and decision behavior are verified in eval/scenarios/architecture/cqrs.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: architecture/hexagonal, architecture/service-layer