Download the PHP package thecorps/laravel-cqrs without Composer

thecorps/laravel-cqrs

🇮🇹 Leggi in italiano

Lightweight CQRS pipeline infrastructure for Laravel applications, built on PHP 8 attributes.

Provides a CommandBus and a QueryBus that route your commands and queries through a fully configurable pipeline of behaviors — logging, validation, database transactions, and handler execution — with zero boilerplate in the consuming code.

Requirements

Installation

Laravel's auto-discovery registers the CqrsServiceProvider and the CommandBus / QueryBus facades automatically. No manual registration needed.

Publishing the configuration file

This creates config/cqrs.php in your application where you can customize the pipeline and logging settings.

How it works

Queries follow the same pattern but skip LoggingBehavior and TransactionBehavior by default.

Usage

1 — Command

A command is an immutable DTO that implements CommandInterface and declares its handler via the #[CommandHandler] attribute.

2 — Command Handler

3 — Dispatch

4 — Query

5 — Validator (optional)

Validators contain domain rules that go beyond HTTP input validation. They are opt-in: without #[CommandValidator], the ValidationBehavior is a no-op.

6 — Transactions

TransactionBehavior is included in the default command pipeline. You do not need to do anything: every command is automatically wrapped in a DB::transaction(). If any exception is thrown — whether from the validator, the handler, or any downstream behavior — the entire transaction is rolled back.

To disable automatic transactions, remove TransactionBehavior from command_pipeline in your published config/cqrs.php:

Note: Never add TransactionBehavior to the query pipeline. Read-only queries do not need transactions.

7 — Logging

LoggingBehavior is included in the default command pipeline. It writes two log entries for every command dispatched: one at dispatch time and one on completion.

By default it uses the application's default log channel at debug level. Both settings are configurable:

To disable logging entirely, remove LoggingBehavior from command_pipeline:

Configuration

After publishing, config/cqrs.php exposes three configuration areas.

Pipeline composition

You can add, remove, or reorder behaviors freely. The order in the array is the execution order.

Custom behaviors

Any class implementing PipelineBehaviorInterface can be inserted into the pipeline. Custom behaviors are resolved from the Laravel container, so they support constructor injection.

Logging

Package structure

Best practices

Keep Commands and Queries as immutable DTOs. Use readonly constructor properties. A command must carry exactly what it needs — no optional nullable fields that mask missing data.

Separate HTTP validation from domain validation. Use Laravel FormRequest to check input format, presence, and types. Use CommandValidator for domain rules: uniqueness, state machine transitions, cross-aggregate constraints.

Handlers must be thin orchestrators. Keep business logic in models, domain services, or value objects. The handler's only job is to coordinate them.

Queries must never write. If you find yourself calling save() inside a query handler, move that logic to a command.

HandlerExecutionBehavior must always be last. Any behavior placed after it will never execute.

Do not add TransactionBehavior to the query pipeline. Wrapping read-only queries in transactions is unnecessary overhead. The default configuration already reflects this.

License

This package is open-source software released under the MIT License.

You are free to use, modify, and distribute it in both private and commercial projects. The only requirement is to keep the copyright notice in any copies or substantial portions of the software.