Initiation à CQRS en PHP vanille : séparer commandes et lectures sans framework

Tu entends parler de CQRS partout mais tu te demandes comment l'appliquer sans dégainer Symfony ou Laravel ? Bonne nouvelle : on peut explorer la Command Query Responsibility Segregation en PHP vanille avec juste une organisation claire et quelques classes bien pensées. Prends ton éditeur, on pose les bases ensemble.

Pré-requis : PHP 8.4 et configuration minimale

• PHP 8.4 installé (CLI ou serveur web). Vérifie ta version avec php -v pour profiter des propriétés readonly, des types stricts et du support natif des first-class callables.
• Composer (optionnel mais pratique pour l'autoloading) et un serveur web léger (php -S 127.0.0.1:8000 -t public suffit pour expérimenter).

Si tu dois rester sur une version antérieure, assure-toi que les features utilisées (constructeurs promotionnés, propriétés readonly, etc.) sont disponibles ou adapte les snippets.

1. CQRS en deux minutes chrono

CQRS consiste à séparer la lecture (Query) de l'écriture (Command). On obtient deux chemins optimisés :

• Les commandes mutent l'état (créer un compte, publier un article) et ne renvoient pas de données applicatives.
• Les requêtes lisent l'état (liste des articles, détail d'un compte) sans effet de bord.

Cette séparation découle naturellement de la philosophie DDD, mais tu peux l'adopter sans tout le formalisme. Les gains immédiats :

• Tests plus simples : tu testes des handlers unitaires.
• Code plus lisible : chaque handler fait une seule chose.
• Scalabilité progressive : tu peux faire évoluer le côté lecture indépendamment du côté écriture.

Rappelle-toi toutefois que CQRS ajoute un peu de complexité structurelle. Sur un CRUD basique, c'est peut-être trop lourd. Utilise-le quand les règles métiers ou les besoins de scalabilité le justifient.

2. Structure de dossier minimale en PHP natif

On peut rester léger avec une arborescence simple :

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

On distingue Domain (règles métier), Application (cas d’usage) et Infrastructure (implémentations concrètes).

3. Modèle métier minimaliste

Créons un agrégat Article et son 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. Côté Command : créer un article

La commande transporte l'intention. Le handler orchestre la logique métier.

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}

Remarque importante : le handler ne retourne rien. Si tu veux relire l’article, tu passeras par une Query.

5. Côté Query : lister les articles

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}

On expose ici un tableau prêt à être sérialisé, sans dépendre du modèle domaine dans la couche présentation.

6. Un repository mémoire pour démarrer

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}

Tu pourras remplacer cette implémentation par une version Doctrine, PDO ou API externe plus tard, sans toucher aux handlers.

7. Mettre en place des bus ultra-légers

Le pattern CQRS devient agréable quand tu centralises la résolution des handlers :

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('Aucun handler pour ' . $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('Aucun handler pour ' . $query::class);
17        }
18
19        return $handler($query);
20    }
21}

Ces bus restent naïfs mais suffisent pour comprendre la mécanique. Dans un vrai projet, tu pourrais les brancher sur un conteneur d’injection de dépendances (PHP-DI, Symfony DI, etc.).

8. Exemple d’amorçage dans 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: 'Premiers pas avec CQRS',
20    content: 'On sépare commandes et lectures en douceur…',
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’opérateur (...) (first-class callable) disponible depuis PHP 8.1 est pleinement pris en charge par PHP 8.4. Si tu dois supporter une version antérieure (8.0 ou moins), remplace-le par fn ($command) => $createHandler($command).

9. Aller plus loin progressivement

Une fois cette base en place, tu peux enrichir ta solution :

1. Validation : ajoute des Value Objects (Titre, Contenu) ou une validation Symfony Validator avant de créer ton agrégat.
2. Persistance réelle : implémente un repository MySQL (PDO) ou PostgreSQL sans toucher aux handlers.
3. Événements de domaine : publie un ArticlePublished quand la commande réussit, puis consomme-le dans une autre couche.
4. Projection dédiée : crée une table optimisée lecture pour les queries gourmandes (pagination, recherche full-text).
5. Tests : écris des tests unitaires pour chaque handler et des tests fonctionnels pour les bus.

10. Checklist pour ta première mise en production

• Chaque commande a un handler dédié qui ne retourne rien.
• Chaque query est isolée et formate les données pour le front.
• Les dépendances techniques sont injectées depuis l’extérieur.
• Les erreurs métiers sont gérées dans le domaine (exceptions spécialisées, Value Objects, etc.).
• Les tests couvrent commandes, queries et bus.

Avec ce squelette, tu peux introduire CQRS progressivement dans un projet existant ou démarrer un nouveau service sans framework. La clé reste de garder la frontière lecture/écriture claire et de faire évoluer ton architecture par itérations. Bonne expérimentation !