Laravel CQRS From Scratch

Dec 19, 2021 5 minutes read
Blocks - Polesie Toys (

The Laravel default structure makes it really easy to start development. But if you got 250+ endpoints, different data sources for reading and combining data it starts to be hard for maintaining. The CQRS pattern could be the answer for that kind of problems. Maybe you already use this sort of things in your project, but you did not know that it is called CQRS. There is also something similar called GraphQL - it is a very similar concept, but it is already a concrete implementation.

If you have been doing software development for a while you probably hear about CQRS. It stands for Command and Query Responsibility Segregation. CQRS is an architectural pattern which advocates splitting the model of information into two parts, namely Command and Query. The motivation behind CQRS is to be able to scale out read and write independently even using different technologies.

You can have a software architecture that has one database for reading data and another one for writing data through commands. CQRS enhances this concept because it allows you to access both databases (for reading and writing) with one language like SQL or MongoDB or other languages like Java or Python. But if your application does not need a high performance database you can start with just one database (most popular case for small and mid projects).

To summarize Commands are responsible for writing (mutation) and Queries are responsible for reading. By default in Laravel you probably use just Eloquent model for both purposes.

Before we start

You need to know that CQRS is a very simple pattern and there is no magic behind. But it also has some disadvantages. Especially because it is a kind of layered (or onion) architectural pattern.

In this example we will create 4 files:

  1. Command
  2. CommandHandler
  3. Query
  4. CommandBus, it is an abstraction to simplify calling the handlers. We will built one in the end of that article.


It is a Plain Old PHP Object (without any relation to the framework). One of the benefits is the naming convention - you know exactly what that object is doing. By type declarations you know what you can expect from the request. In some terms it is just immutable DTO (Data Transfer Object) from one layer to another one.


namespace App\Commands;

class CreateProductCommand
    private $name;
    private $price;

    public function __construct($name, $price)
        $this->name = $name;
        $this->price = $price;

    public function getName(): string
        return $this->name;

    public function getPrice(): float
        return $this->price;


Handler is responsible for processing the Command. There is one main rule, one Command must have exactly one CommandHandler. In our example we must create Commands and Handlers in the same namespace.


namespace App\Commands;

use App\Models\Product;

class CreateProductHandler
    public function __invoke(CreateProductCommand $command)
    	$product = new Product();
    	$product->name = $command->getName();
    	$product->price = $command->getPrice();
    	// other logic, eg queue slack notification, dispatch event etc.


Queries are responsible for reading data from your application. Here you can connect to multiple data sources such as databases, APIs, and finally combine them and build a response for the data client (Blade view, API response, etc).

As for the format of the returned data from Queries, some sources say that you should create dedicated objects (DTO) that will be read by other layers. However, in my experience it introduces a lot of boilerplate, which still generates another problem - serialization of this data. Therefore, the easiest way to use (in the case of PHP) is just any "Arrayable" type structure - the simplest arrays.

Arrays will make it easier for you to return data from controllers or accessing via Blade. Beside that accessing arrays in Laravel is quite pleasant -  thanks to the data_get method, e.g. data_get($array, ''). Therefore, in the example below, we simply return an array.


namespace App\Queries;

use App\Models\Product;

class ProductSimpleQuery
    private $productId;

    public function __construct(int $productId)
        $this->productId = $productId;

    public function getData(): array
        $product = Product::query()->findOrFail($this->productId);
        return [
            'name' => $product->name,
            'price' => $product->price,


CommandBus has a single responsibility which is to execute all Commands in the system. It could be injected in your controllers or any other place you want to dispatch commands. It's a good idea to use dependency injection whenever you want to use it. Laravel supports auto wiring, so it should work out-of-the-box.


namespace App;

use Illuminate\Support\Facades\App;
use ReflectionClass;

class CommandBus
    public function handle($command)
        // resolve handler
        $reflection = new ReflectionClass($command);
        $handlerName = str_replace("Command", "Handler", $reflection->getShortName());
        $handlerName = str_replace($reflection->getShortName(), $handlerName, $reflection->getName());
        $handler = App::make($handlerName);
        // invoke handler



namespace App\Http\Controllers;

use App\CommandBus;
use App\Commands\CreateProductCommand;
use App\Queries\ProductSimpleQuery;

class ProductController extends Controller
    private $commandBus;

    public function __construct(CommandBus $commandBus)
        $this->commandBus = $commandBus;

    public function details(int $id)
    	// $this->authorize('...')
        $query = new ProductSimpleQuery($id);
        return $query->getData();

    public function create()
        // $this->authorize('...')
        $name = request()->query('name');
        $price = request()->query('price');
        // validation goes here ...
        $command = new CreateProductCommand($name, $price);

        return response()->json([
            'message' => 'success',


As you can see it is very simple. With about 100 lines of code we built up a generic way of triggering Commands in the Laravel application. By using that pattern you can improve your project and make it easy to understand for new developers who will join your team.

What could we do to enhance that implementation:

  • Logging mechanism in CommandBus - it would be helpful even for business purpose to see some statistics of application usage.
  • Create database transactions support. It is very helpful for protecting your data flow.
  • handleMultiple method - sometimes you want to trigger more than one command (e.g. Edit and Submit)
  • and more…

Hope I have fully explained the theory of this pattern and the content has been valuable to you. As you can imagine there are many ways of implementing CQRS, but the concept stays same. All depends on your expectations and needs.

➡️  Part 2: Laravel Advanced CQRS ⬅️

If you like the whole idea about CQRS and you want to learn more about that pattern I strongly recommend that article on the Microsoft Tech Blog (CQRS pattern)

Disclaimer: The opinions expressed here are my own and do not necessarily represent those of current or past employers.
Comments (1)