Introduzione a CQRS in PHP puro: separa comandi e letture senza framework

Senti parlare di CQRS ovunque ma ti chiedi come applicarlo senza tirare fuori Symfony o Laravel? Buone notizie: possiamo esplorare la Command Query Responsibility Segregation in PHP puro con una semplice organizzazione e poche classi ben pensate. Apri l’editor, gettiamo insieme le fondamenta.

Prerequisiti: PHP 8.4 e configurazione minima

• PHP 8.4 installato (CLI o server web). Verifica la tua versione con php -v per sfruttare le proprietà readonly, i tipi strict e il supporto nativo ai first-class callables.
• Composer (opzionale ma comodo per l’autoloading) e un server web leggero (php -S 127.0.0.1:8000 -t public è sufficiente per fare prove).

Se devi restare su una versione precedente, assicurati che le funzionalità utilizzate (promozione del costruttore, proprietà readonly, ecc.) siano disponibili oppure adatta gli snippet.

1. CQRS in due minuti

CQRS significa separare la lettura (Query) dalla scrittura (Command). Ottieni così due percorsi ottimizzati:

• I comandi modificano lo stato (creare un account, pubblicare un articolo) e non restituiscono dati applicativi.
• Le query leggono lo stato (elenco degli articoli, dettaglio di un account) senza effetti collaterali.

Questa separazione nasce dalla filosofia del DDD, ma puoi adottarla senza eccessivo formalismo. Benefici immediati:

• Test più semplici: testi i handler in maniera unitaria.
• Codice più leggibile: ogni handler fa una sola cosa.
• Scalabilità progressiva: puoi far evolvere il lato lettura in modo indipendente dal lato scrittura.

Ricorda però che CQRS introduce un po’ di complessità strutturale. Su un semplice CRUD potrebbe essere eccessivo. Usalo quando le regole di business o le esigenze di scalabilità lo richiedono.

2. Struttura di cartelle minimale in PHP nativo

Possiamo restare leggeri con un albero molto semplice:

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

Separiamo chiaramente Domain (regole di business), Application (casi d’uso) e Infrastructure (implementazioni concrete).

3. Modello di dominio minimalista

Creiamo un aggregato Article e il suo repository:

php
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}

php
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}

4. Lato Command: creare un articolo

Il comando trasporta l’intenzione. L’handler orchestra la logica di business.

php
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}

php
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}

Nota importante: l’handler non restituisce nulla. Se vuoi leggere di nuovo l’articolo, passerai da una Query.

5. Lato Query: elencare gli articoli

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

php
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}

Esporre un array già pronto per la serializzazione evita di legare la presentazione al modello di dominio.

6. Un repository in memoria per partire

php
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}

Potrai sostituire questa implementazione con Doctrine, PDO o un’API esterna in seguito senza toccare gli handler.

7. Mettere in piedi bus ultraleggeri

Il pattern CQRS diventa piacevole quando centralizzi la risoluzione degli handler:

php
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): void
12    {
13        $handler = $this->handlers[$command::class] ?? null;
14
15        if ($handler === null) {
16            throw new \RuntimeException('Nessun handler per ' . $command::class);
17        }
18
19        $handler($command);
20    }
21}

php
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): mixed
12    {
13        $handler = $this->handlers[$query::class] ?? null;
14
15        if ($handler === null) {
16            throw new \RuntimeException('Nessun handler per ' . $query::class);
17        }
18
19        return $handler($query);
20    }
21}

Questi bus restano basilari ma bastano per comprendere la meccanica. In un progetto reale potresti collegarli a un contenitore di dependency injection (PHP-DI, Symfony DI, ecc.).

8. Esempio di bootstrap in public/index.php

php
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    CreateArticleCommand::class => $createHandler(...),
11]);
12
13$queryBus = new QueryBus([
14    ListArticlesQuery::class => $listHandler(...),
15]);
16
17$commandBus->dispatch(new CreateArticleCommand(
18    id: uniqid('article_', true),
19    title: 'Primi passi con CQRS',
20    content: 'Separiamo comandi e letture con gradualità…',
21    publishedAt: '2025-06-05 10:00:00',
22));
23
24$articles = $queryBus->ask(new ListArticlesQuery());
25
26header('Content-Type: application/json');
27echo json_encode($articles, JSON_PRETTY_PRINT);

L’operatore (...) (first-class callable), disponibile da PHP 8.1, è pienamente supportato in PHP 8.4. Se devi supportare una versione precedente (8.0 o inferiore), sostituiscilo con fn ($command) => $createHandler($command).

9. Progredire passo dopo passo

Una volta gettate le basi, puoi arricchire la soluzione:

1. Validazione: aggiungi Value Object (Titolo, Contenuto) o una validazione con Symfony Validator prima di creare l’aggregato.
2. Persistenza reale: implementa un repository MySQL (PDO) o PostgreSQL senza toccare gli handler.
3. Eventi di dominio: pubblica un ArticlePublished quando il comando va a buon fine e consumalo in un altro livello.
4. Proiezione dedicata: crea una tabella ottimizzata per la lettura per query esigenti (paginazione, ricerca full-text).
5. Test: scrivi test unitari per ogni handler e test funzionali per i bus.

10. Checklist per la prima messa in produzione

• Ogni comando ha un handler dedicato che non restituisce nulla.
• Ogni query è isolata e formatta i dati per il front-end.
• Le dipendenze tecniche vengono iniettate dall’esterno.
• Gli errori di business sono gestiti nel dominio (eccezioni specializzate, Value Object, ecc.).
• I test coprono comandi, query e bus.

Con questo scheletro puoi introdurre CQRS gradualmente in un progetto esistente o avviare un nuovo servizio senza framework. La chiave è mantenere chiaro il confine tra lettura e scrittura e far evolvere l’architettura per iterazioni. Buona sperimentazione!