CQRS Pattern

Also Known As

TL;DR

Explanation

CQRS separates an application into two distinct sides: the command side handles write operations (create, update, delete) through command objects processed by command handlers, updating a normalised write model; the query side handles read operations through query objects processed by query handlers, reading from a denormalised read model optimised for display. The read model can be a database view, a cached projection, a separate database, or even a different storage technology than the write model. In its simplest form, CQRS in PHP is just a coding pattern — separate service classes for reads and writes, no shared models. In advanced implementations, the read model is derived from events emitted by the write model (event sourcing), enabling separate scaling, separate databases, and rebuilding the read model from scratch by replaying events. Laravel has several CQRS libraries (Tactician, Broadway); Symfony provides the Messenger component which fits the command bus pattern.

Common Misconception

Why It Matters

Common Mistakes

• Applying CQRS to every part of the application — it adds complexity and is only justified where read/write models genuinely diverge or where separate scaling is needed.
• Returning data from command handlers — commands should return void or a command ID; read the updated state with a query if needed.
• Keeping the read and write models in sync synchronously when they are meant to be eventually consistent — this negates the performance benefit of separate models.
• Starting with the full event sourcing implementation before validating that the simpler CQRS separation solves the problem — YAGNI applies.

Avoid When

• Simple CRUD applications with straightforward read/write patterns where the added complexity of separate models provides no performance or scalability benefit.
• Teams unfamiliar with event-driven architecture or asynchronous messaging, as CQRS introduces operational complexity that requires solid infrastructure and debugging practices.
• Systems where read and write models must stay perfectly consistent in real-time, since eventual consistency between separated models is often difficult to eliminate.
• Projects with tight deadlines or limited budget, as the initial overhead of implementing dual models typically delays feature delivery compared to a unified model approach.

When To Use

• Your read and write loads are asymmetrical — queries vastly outnumber writes or require different optimization strategies (caching, denormalisation, separate scaling).
• You need an audit trail or event history of state changes — event sourcing with CQRS gives you a complete record and the ability to rebuild read models.
• Your read model requires a shape different from your write model — for example, writes normalise data into relational tables but reads need a flat, denormalised view for performance.
• You're building a system where multiple services or teams need to consume the same data in different shapes — CQRS lets each service maintain its own optimised read projection.

Code Examples

// Mixed read/write in one service — tight coupling
class OrderService {
    public function createOrder(array $data): Order {
        $order = Order::create($data);
        // Read mixed with write
        return Order::with(['items', 'user', 'address'])
            ->find($order->id); // N+1, heavy join for a write operation
    }
}

// Separate command and query handlers
class CreateOrderHandler {
    public function handle(CreateOrder $cmd): string {
        $order = new Order($cmd->customerId, $cmd->items);
        $this->orders->save($order);
        $this->eventBus->publish(new OrderCreated($order->id));
        return $order->id; // return ID only, not full read model
    }
}

class OrderSummaryQuery {
    public function findById(string $id): OrderSummaryDTO {
        // Reads from denormalised read model — fast, no joins
        return $this->readDb->query(
            'SELECT * FROM order_summaries WHERE id = ?', [$id]
        );
    }
}

Tags

🧠 Logic Engine

References

• https://martinfowler.com/bliki/CQRS.html
• https://symfony.com/doc/current/messenger.html