Iniciación a CQRS en PHP puro: separa comandos y lecturas sin framework

¿Escuchas hablar de CQRS por todas partes pero te preguntas cómo aplicarlo sin tirar de Symfony o Laravel? Buena noticia: podemos explorar la Command Query Responsibility Segregation en PHP puro con solo una organización clara y unas cuantas clases bien pensadas. Abre tu editor, asentamos las bases juntos.

Requisitos previos: PHP 8.4 y configuración mínima

PHP 8.4 instalado (CLI o servidor web). Comprueba tu versión con para aprovechar las propiedades , los tipos estrictos y el soporte nativo de los first-class callables.
Composer (opcional pero práctico para el autoloading) y un servidor web ligero ( basta para experimentar).

Si debes quedarte en una versión anterior, asegúrate de que las características usadas aquí (promoción de constructores, propiedades , etc.) estén disponibles o adapta los fragmentos.

1. CQRS en dos minutos

CQRS consiste en separar la lectura (Query) de la escritura (Command). Obtienes dos caminos optimizados:

Los comandos mutan el estado (crear una cuenta, publicar un artículo) y no devuelven datos de aplicación.
Las consultas (queries) leen el estado (listar artículos, obtener el detalle de una cuenta) sin efectos secundarios.

Esta separación nace de la filosofía DDD, pero puedes adoptarla sin todo el formalismo. Beneficios inmediatos:

Tests más sencillos: pruebas handlers unitarios.
Código más legible: cada handler hace una sola cosa.
Escalabilidad progresiva: puedes hacer evolucionar el lado lectura de forma independiente del lado escritura.

Recuerda que CQRS añade algo de complejidad estructural. En un CRUD básico puede resultar demasiado. Úsalo cuando las reglas de negocio o las necesidades de escalabilidad lo justifiquen.

2. Estructura de carpetas mínima en PHP nativo

Podemos mantenernos ligeros con un árbol simple:

Distinguimos Domain (reglas de negocio), Application (casos de uso) e Infrastructure (implementaciones concretas).

3. Modelo de dominio minimalista

Creemos un agregado y su repositorio:

4. Lado Command: crear un artículo

El comando transporta la intención. El handler orquesta la lógica de negocio.

Nota importante: el handler no devuelve nada. Si quieres volver a leer el artículo, pasarás por una consulta (Query).

5. Lado Query: listar los artículos

Exponemos aquí un array listo para serializarse, sin depender del modelo de dominio en la capa de presentación.

6. Un repositorio en memoria para empezar

Podrás reemplazar esta implementación por una versión con Doctrine, PDO o una API externa más adelante, sin tocar los handlers.

Requisitos previos: PHP 8.4 y configuración mínima

PHP 8.4 instalado (CLI o servidor web). Comprueba tu versión con para aprovechar las propiedades , los tipos estrictos y el soporte nativo de los first-class callables.
Composer (opcional pero práctico para el autoloading) y un servidor web ligero ( basta para experimentar).

Si debes quedarte en una versión anterior, asegúrate de que las características usadas aquí (promoción de constructores, propiedades , etc.) estén disponibles o adapta los fragmentos.

1. CQRS en dos minutos

CQRS consiste en separar la lectura (Query) de la escritura (Command). Obtienes dos caminos optimizados:

Los comandos mutan el estado (crear una cuenta, publicar un artículo) y no devuelven datos de aplicación.
Las consultas (queries) leen el estado (listar artículos, obtener el detalle de una cuenta) sin efectos secundarios.

Esta separación nace de la filosofía DDD, pero puedes adoptarla sin todo el formalismo. Beneficios inmediatos:

Tests más sencillos: pruebas handlers unitarios.
Código más legible: cada handler hace una sola cosa.
Escalabilidad progresiva: puedes hacer evolucionar el lado lectura de forma independiente del lado escritura.

Recuerda que CQRS añade algo de complejidad estructural. En un CRUD básico puede resultar demasiado. Úsalo cuando las reglas de negocio o las necesidades de escalabilidad lo justifiquen.

2. Estructura de carpetas mínima en PHP nativo

Podemos mantenernos ligeros con un árbol simple:

Distinguimos Domain (reglas de negocio), Application (casos de uso) e Infrastructure (implementaciones concretas).

3. Modelo de dominio minimalista

Creemos un agregado y su repositorio:

4. Lado Command: crear un artículo

El comando transporta la intención. El handler orquesta la lógica de negocio.

Nota importante: el handler no devuelve nada. Si quieres volver a leer el artículo, pasarás por una consulta (Query).

5. Lado Query: listar los artículos

Exponemos aquí un array listo para serializarse, sin depender del modelo de dominio en la capa de presentación.

6. Un repositorio en memoria para empezar

Podrás reemplazar esta implementación por una versión con Doctrine, PDO o una API externa más adelante, sin tocar los 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

Iniciación a CQRS en PHP puro: separa comandos y lecturas sin framework

Iniciación a CQRS en PHP puro: separa comandos y lecturas sin framework

Requisitos previos: PHP 8.4 y configuración mínima

1. CQRS en dos minutos

2. Estructura de carpetas mínima en PHP nativo

3. Modelo de dominio minimalista

4. Lado Command: crear un artículo

5. Lado Query: listar los artículos

6. Un repositorio en memoria para empezar

Requisitos previos: PHP 8.4 y configuración mínima

1. CQRS en dos minutos

2. Estructura de carpetas mínima en PHP nativo

3. Modelo de dominio minimalista

4. Lado Command: crear un artículo

5. Lado Query: listar los artículos

6. Un repositorio en memoria para empezar

7. Monta buses ultraligeros

8. Ejemplo de arranque en `public/index.php`

9. Avanza poco a poco

10. Checklist para tu primera puesta en producción

Iniciación a CQRS en PHP puro: separa comandos y lecturas sin framework

Iniciación a CQRS en PHP puro: separa comandos y lecturas sin framework

Requisitos previos: PHP 8.4 y configuración mínima

1. CQRS en dos minutos

2. Estructura de carpetas mínima en PHP nativo

3. Modelo de dominio minimalista

4. Lado Command: crear un artículo

5. Lado Query: listar los artículos

6. Un repositorio en memoria para empezar

Requisitos previos: PHP 8.4 y configuración mínima

1. CQRS en dos minutos

2. Estructura de carpetas mínima en PHP nativo

3. Modelo de dominio minimalista

4. Lado Command: crear un artículo

5. Lado Query: listar los artículos

6. Un repositorio en memoria para empezar

7. Monta buses ultraligeros

8. Ejemplo de arranque en public/index.php

9. Avanza poco a poco

10. Checklist para tu primera puesta en producción

8. Ejemplo de arranque en `public/index.php`