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 per sfruttare le proprietà , i tipi strict e il supporto nativo ai first-class callables.
Composer (opzionale ma comodo per l’autoloading) e un server web leggero ( è sufficiente per fare prove).

Se devi restare su una versione precedente, assicurati che le funzionalità utilizzate (promozione del costruttore, proprietà , 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:

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

3. Modello di dominio minimalista

Creiamo un aggregato e il suo repository:

4. Lato Command: creare un articolo

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

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

5. Lato Query: elencare gli articoli

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

6. Un repository in memoria per partire

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

Prerequisiti: PHP 8.4 e configurazione minima

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

Se devi restare su una versione precedente, assicurati che le funzionalità utilizzate (promozione del costruttore, proprietà , 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:

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

3. Modello di dominio minimalista

Creiamo un aggregato e il suo repository:

4. Lato Command: creare un articolo

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

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

5. Lato Query: elencare gli articoli

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

6. Un repository in memoria per partire

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

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

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

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

Prerequisiti: PHP 8.4 e configurazione minima

1. CQRS in due minuti

2. Struttura di cartelle minimale in PHP nativo

3. Modello di dominio minimalista

4. Lato Command: creare un articolo

5. Lato Query: elencare gli articoli

6. Un repository in memoria per partire

Prerequisiti: PHP 8.4 e configurazione minima

1. CQRS in due minuti

2. Struttura di cartelle minimale in PHP nativo

3. Modello di dominio minimalista

4. Lato Command: creare un articolo

5. Lato Query: elencare gli articoli

6. Un repository in memoria per partire

7. Mettere in piedi bus ultraleggeri

8. Esempio di bootstrap in `public/index.php`

9. Progredire passo dopo passo

10. Checklist per la prima messa in produzione

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

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

Prerequisiti: PHP 8.4 e configurazione minima

1. CQRS in due minuti

2. Struttura di cartelle minimale in PHP nativo

3. Modello di dominio minimalista

4. Lato Command: creare un articolo

5. Lato Query: elencare gli articoli

6. Un repository in memoria per partire

Prerequisiti: PHP 8.4 e configurazione minima

1. CQRS in due minuti

2. Struttura di cartelle minimale in PHP nativo

3. Modello di dominio minimalista

4. Lato Command: creare un articolo

5. Lato Query: elencare gli articoli

6. Un repository in memoria per partire

7. Mettere in piedi bus ultraleggeri

8. Esempio di bootstrap in public/index.php

9. Progredire passo dopo passo

10. Checklist per la prima messa in produzione

8. Esempio di bootstrap in `public/index.php`