Einstieg in CQRS mit Vanilla-PHP: Befehle und Lesezugriffe ohne Framework trennen

Du hörst überall von CQRS, fragst dich aber, wie du es anwenden kannst, ohne sofort Symfony oder Laravel auszupacken? Gute Nachricht: Wir können Command Query Responsibility Segregation in purem PHP erkunden – mit einer klaren Organisation und ein paar gut durchdachten Klassen. Schnapp dir deinen Editor, wir legen gemeinsam die Basis.

Voraussetzungen: PHP 8.4 und ein minimales Setup

• PHP 8.4 installiert (CLI oder Webserver). Prüfe deine Version mit php -v, um readonly-Properties, strikte Typen und native First-Class Callables zu nutzen.
• Composer (optional, aber praktisch fürs Autoloading) sowie ein leichter Webserver (php -S 127.0.0.1:8000 -t public reicht zum Experimentieren).

Wenn du bei einer älteren Version bleiben musst, stelle sicher, dass die verwendeten Features (Konstruktor-Promotion, readonly-Properties usw.) verfügbar sind oder passe die Snippets an.

1. CQRS in zwei Minuten

CQRS bedeutet, Lesen (Query) und Schreiben (Command) strikt zu trennen. Daraus entstehen zwei optimierte Pfade:

• Commands verändern den Zustand (Account anlegen, Artikel veröffentlichen) und liefern keine Anwendungsdaten zurück.
• Queries lesen den Zustand (Artikel auflisten, Account-Details abrufen) ohne Seiteneffekte.

Diese Trennung entspringt zwar der DDD-Philosophie, aber du kannst sie auch ohne viel Formalismus übernehmen. Sofortige Vorteile:

• Einfachere Tests: Handler lassen sich isoliert unit-testen.
• Besser lesbarer Code: Jeder Handler hat nur eine Aufgabe.
• Schrittweise Skalierung: Lese- und Schreibseite können unabhängig voneinander wachsen.

Denke daran, dass CQRS etwas strukturelle Komplexität mitbringt. Für ein simples CRUD kann das zu viel sein. Nutze es, wenn Geschäftslogik oder Skalierungsanforderungen den Aufwand rechtfertigen.

2. Minimale Ordnerstruktur in nativem PHP

Wir bleiben schlank mit einem einfachen Verzeichnisbaum:

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

So trennen wir Domain (Geschäftsregeln), Application (Use Cases) und Infrastructure (konkrete Implementierungen).

3. Ein minimalistisches Domänenmodell

Wir erstellen ein Article-Aggregat und sein 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. Command-Seite: Einen Artikel erstellen

Der Command transportiert die Absicht. Der Handler orchestriert die Geschäftslogik.

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}

Wichtiger Hinweis: Der Handler gibt nichts zurück. Wenn du den Artikel erneut lesen möchtest, gehst du über eine Query.

5. Query-Seite: Artikel auflisten

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}

Wir liefern hier ein Array, das direkt serialisiert werden kann, ohne die Präsentationsschicht an das Domänenmodell zu koppeln.

6. Ein In-Memory-Repository zum Starten

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}

Später kannst du diese Implementierung durch Doctrine, PDO oder eine externe API ersetzen – ohne die Handler anzufassen.

7. Ultraleichte Busse verdrahten

Der CQRS-Ansatz glänzt, sobald du die Handler-Auflösung zentralisierst:

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('Kein Handler für ' . $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('Kein Handler für ' . $query::class);
17        }
18
19        return $handler($query);
20    }
21}

Diese Busse sind bewusst simpel, reichen aber, um das Prinzip zu verstehen. In echten Projekten kannst du sie an einen Dependency-Injection-Container (PHP-DI, Symfony DI usw.) anbinden.

8. Bootstrap-Beispiel 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: 'Erste Schritte mit CQRS',
20    content: 'Wir trennen Commands und Lesezugriffe ganz entspannt…',
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);

Der Operator (...) (First-Class Callable), seit PHP 8.1 verfügbar, wird in PHP 8.4 vollständig unterstützt. Musst du eine ältere Version (8.0 oder niedriger) bedienen, ersetze ihn durch fn ($command) => $createHandler($command).

9. Schrittweise weitergehen

Steht dieses Fundament, kannst du deine Lösung ausbauen:

1. Validierung: Ergänze Value Objects (Title, Content) oder setze vor dem Aggregat Symfony Validator ein.
2. Echte Persistenz: Implementiere ein MySQL- (PDO) oder PostgreSQL-Repository, ohne die Handler zu ändern.
3. Domänenereignisse: Veröffentliche ein ArticlePublished, wenn der Command erfolgreich war, und konsumiere es in einer anderen Schicht.
4. Dedizierte Projektion: Lege für anspruchsvolle Queries (Pagination, Volltextsuche) eine lesefreundliche Tabelle an.
5. Tests: Schreibe Unit-Tests für jeden Handler und funktionale Tests für die Busse.

10. Checkliste für den ersten Produktionseinsatz

• Jeder Command hat einen eigenen Handler, der nichts zurückgibt.
• Jede Query ist isoliert und formatiert Daten für das Frontend.
• Technische Abhängigkeiten werden von außen injiziert.
• Fachliche Fehler werden in der Domain behandelt (spezialisierte Exceptions, Value Objects usw.).
• Tests decken Commands, Queries und Busse ab.

Mit diesem Gerüst kannst du CQRS schrittweise in ein bestehendes Projekt einführen oder einen neuen Service ohne Framework starten. Entscheidend ist, die Grenze zwischen Lesen und Schreiben klar zu halten und die Architektur iterativ weiterzuentwickeln. Viel Erfolg beim Experimentieren!