Getting Started with CQRS in Vanilla PHP: Split Commands and Reads without a Framework

You keep hearing about CQRS everywhere yet wonder how to apply it without pulling out Symfony or Laravel? Good news: we can explore Command Query Responsibility Segregation in vanilla PHP with nothing more than a clear organization and a handful of well-thought-out classes. Grab your editor, let’s lay the foundations together.

Prerequisites: PHP 8.4 and a minimal setup

PHP 8.4 installed (CLI or web server). Check your version with to benefit from properties, strict types, and native support for first-class callables.
Composer (optional but handy for autoloading) and a lightweight web server ( is enough for experimenting).

If you must stay on an earlier version, make sure the features used here (constructor promotion, properties, etc.) are available or adapt the snippets accordingly.

1. CQRS in two minutes flat

CQRS is all about splitting reads (Query) from writes (Command). You end up with two optimized paths:

Commands mutate state (create an account, publish an article) and don’t return application data.
Queries read state (list articles, fetch an account detail) without side effects.

This separation naturally follows DDD principles, but you can adopt it without heavy formalism. Immediate benefits include:

Simpler tests: you unit test handlers in isolation.
Clearer code: every handler does exactly one thing.
Gradual scalability: you can evolve the read side independently from the write side.

Remember that CQRS adds some structural complexity. For a basic CRUD, it might feel overkill. Use it when business rules or scalability needs justify the extra structure.

2. Minimal folder structure in native PHP

We can stay lightweight with a simple tree:

We clearly separate Domain (business rules), Application (use cases), and Infrastructure (concrete implementations).

3. A minimalist domain model

Let’s create an aggregate and its repository:

4. Command side: creating an article

The command carries the intent. The handler orchestrates the business logic.

Important note: the handler returns nothing. If you want to read the article back, you’ll go through a Query.

5. Query side: listing articles

We expose an array that’s ready to be serialized, without tying the presentation layer to the domain model.

6. An in-memory repository to get started

You can swap this implementation for Doctrine, PDO, or an external API later on without touching the handlers.

Prerequisites: PHP 8.4 and a minimal setup

PHP 8.4 installed (CLI or web server). Check your version with to benefit from properties, strict types, and native support for first-class callables.
Composer (optional but handy for autoloading) and a lightweight web server ( is enough for experimenting).

If you must stay on an earlier version, make sure the features used here (constructor promotion, properties, etc.) are available or adapt the snippets accordingly.

1. CQRS in two minutes flat

CQRS is all about splitting reads (Query) from writes (Command). You end up with two optimized paths:

Commands mutate state (create an account, publish an article) and don’t return application data.
Queries read state (list articles, fetch an account detail) without side effects.

This separation naturally follows DDD principles, but you can adopt it without heavy formalism. Immediate benefits include:

Simpler tests: you unit test handlers in isolation.
Clearer code: every handler does exactly one thing.
Gradual scalability: you can evolve the read side independently from the write side.

Remember that CQRS adds some structural complexity. For a basic CRUD, it might feel overkill. Use it when business rules or scalability needs justify the extra structure.

2. Minimal folder structure in native PHP

We can stay lightweight with a simple tree:

We clearly separate Domain (business rules), Application (use cases), and Infrastructure (concrete implementations).

3. A minimalist domain model

Let’s create an aggregate and its repository:

4. Command side: creating an article

The command carries the intent. The handler orchestrates the business logic.

Important note: the handler returns nothing. If you want to read the article back, you’ll go through a Query.

5. Query side: listing articles

We expose an array that’s ready to be serialized, without tying the presentation layer to the domain model.

6. An in-memory repository to get started

You can swap this implementation for Doctrine, PDO, or an external API later on without touching the handlers.

php

php

php

php -v

readonly

php -S 127.0.0.1:8000 -t public

readonly

src/
  Domain/
    Article.php
    ArticleRepository.php
  Application/
    Command/
      CreateArticle/
        CreateArticleCommand.php
        CreateArticleHandler.php
    Query/
      ListArticles/
        ListArticlesQuery.php
        ListArticlesHandler.php
    Bus/
      CommandBus.php
      QueryBus.php
  Infrastructure/
    InMemoryArticleRepository.php
public/
  index.php

Article

1<?php
2// src/Domain/Article.php
3
4final class Article
5{
6    public function __construct(
7        private readonly string $id,
8        private string $title,
9        private string $content,
10        private readonly \DateTimeImmutable $publishedAt,
11    ) {
12    }
13
14    public function id(): string
15    {
16        return $this->id;
17    }
18
19    public function title(): string
20    {
21        return $this->title;
22    }
23
24    public function content(): string
25    {
26        return $this->content;
27    }
28
29    public function publishedAt(): \DateTimeImmutable
30    {
31        return $this->publishedAt;
32    }
33}

1<?php
2// src/Domain/ArticleRepository.php
3
4interface ArticleRepository
5{
6    public function save(Article $article): void;
7
8    /** @return Article[] */
9    public function all(): array;
10}

1<?php
2// src/Application/Command/CreateArticle/CreateArticleCommand.php
3
4final class CreateArticleCommand
5{
6    public function __construct(
7        public readonly string $id,
8        public readonly string $title,
9        public readonly string $content,
10        public readonly string $publishedAt,
11    ) {
12    }
13}

1<?php
2// src/Application/Command/CreateArticle/CreateArticleHandler.php
3
4final class CreateArticleHandler
5{
6    public function __construct(private ArticleRepository $repository)
7    {
8    }
9
10    public function __invoke(CreateArticleCommand $command): void
11    {
12        $article = new Article(
13            $command->id,
14            $command->title,
15            $command->content,
16            new \DateTimeImmutable($command->publishedAt),
17        );
18
19        $this->repository->save($article);
20    }
21}

1<?php
2// src/Application/Query/ListArticles/ListArticlesQuery.php
3
4final class ListArticlesQuery
5{
6}

1<?php
2// src/Application/Query/ListArticles/ListArticlesHandler.php
3
4final class ListArticlesHandler
5{
6    public function __construct(private ArticleRepository $repository)
7    {
8    }
9
10    /** @return array<int, array{id: string, title: string, publishedAt: string}> */
11    public function __invoke(ListArticlesQuery $query): array
12    {
13        return array_map(
14            static fn (Article $article) => [
15                'id' => $article->id(),
16                'title' => $article->title(),
17                'publishedAt' => $article->publishedAt()->format('Y-m-d H:i:s'),
18            ],
19            $this->repository->all()
20        );
21    }
22}

1<?php
2// src/Infrastructure/InMemoryArticleRepository.php
3
4final class InMemoryArticleRepository implements ArticleRepository
5{
6    /** @var array<string, Article> */
7    private array $storage = [];
8
9    public function save(Article $article): void
10    {
11        $this->storage[$article->id()] = $article;
12    }
13
14    public function all(): array
15    {
16        return array_values($this->storage);
17    }
18}

1<?php
2// src/Application/Bus/CommandBus.php
3
4final class CommandBus
5{
6    /** @param array<class-string, callable> $handlers */
7    public function __construct(private array $handlers)
8    {
9    }
10
11    public function dispatch(object $command)

1<?php
2// src/Application/Bus/QueryBus.php
3
4final class QueryBus
5{
6    /** @param array<class-string, callable> $handlers */
7    public function __construct(private array $handlers)
8    {
9    }
10
11    public function ask(object $query)

1<?php
2require_once __DIR__ . '/../vendor/autoload.php';
3
4$repository = new InMemoryArticleRepository();
5
6$createHandler = new CreateArticleHandler($repository);
7$listHandler = new ListArticlesHandler($repository);
8
9$commandBus = new CommandBus([
10

Getting Started with CQRS in Vanilla PHP: Split Commands and Reads without a Framework

Getting Started with CQRS in Vanilla PHP: Split Commands and Reads without a Framework

Prerequisites: PHP 8.4 and a minimal setup

1. CQRS in two minutes flat

2. Minimal folder structure in native PHP

3. A minimalist domain model

4. Command side: creating an article

5. Query side: listing articles

6. An in-memory repository to get started

Prerequisites: PHP 8.4 and a minimal setup

1. CQRS in two minutes flat

2. Minimal folder structure in native PHP

3. A minimalist domain model

4. Command side: creating an article

5. Query side: listing articles

6. An in-memory repository to get started

7. Wiring ultra-light buses

8. Bootstrapping example in `public/index.php`

9. Going further step by step

10. Checklist for your first production release

Getting Started with CQRS in Vanilla PHP: Split Commands and Reads without a Framework

Getting Started with CQRS in Vanilla PHP: Split Commands and Reads without a Framework

Prerequisites: PHP 8.4 and a minimal setup

1. CQRS in two minutes flat

2. Minimal folder structure in native PHP

3. A minimalist domain model

4. Command side: creating an article

5. Query side: listing articles

6. An in-memory repository to get started

Prerequisites: PHP 8.4 and a minimal setup

1. CQRS in two minutes flat

2. Minimal folder structure in native PHP

3. A minimalist domain model

4. Command side: creating an article

5. Query side: listing articles

6. An in-memory repository to get started

7. Wiring ultra-light buses

8. Bootstrapping example in public/index.php

9. Going further step by step

10. Checklist for your first production release

8. Bootstrapping example in `public/index.php`