Kapitola 10 · Architektura · Implementace DDD v Symfony 8

Implementace DDD v Symfony 8

DDD koncepty přeložené do Symfony 8: struktura projektu podle Bounded Contextů, persistence agregátů přes Doctrine, konfigurace Messengeru a Doctrine custom types pro hodnotové objekty.

Autor M. Katuščák

Doba čtení ≈ 42 min

Náročnost pokročilá

Publikováno · Aktualizováno 24. 4. 2025 · 29. 9. 2026

Obsah kapitoly

§ Poznámka

Mapping volba: atributy jako výchozí přístup

Tento průvodce používá Doctrine atributy přímo na doménových třídách (#[ORM\Entity], #[ORM\Column]). Argumentem proti je porušení Dependency Inversion: doména „ví“ o Doctrine. Jde přitom o metadata, ne o chování: třída se chová stejně, pouze nese popisek pro mapper. Symfony Best Practices doporučují atributy výslovně („Use Attributes to Define the Doctrine Entity Mapping“) [1] a Symfony Maker jiný formát negeneruje.

XML mapping doménu od ORM neoddělí, jen přesune metadata do jiného souboru. Skutečné oddělení nabízí Persisted Object Pattern: samostatná persistence třída a mapper na doménový agregát. Je to menšinová volba s doloženou cenou, kterou rozebírá sekce Persisted Object Pattern.

10.01 Kde končí DDD a kde začíná Symfony#

Diagram ukazuje hranici mezi čistým DDD kódem (zelená oblast) a Symfony infrastrukturou (oranžová oblast). Vše v zelené oblasti je čisté PHP bez závislosti na frameworku, testovatelné v izolaci a přenositelné mezi projekty. Kniha doméně vědomě povoluje jen symfony/uid pro generování identit a z Doctrine mapovací atributy a kolekce (Doctrine\ORM\Mapping, Doctrine\Common\Collections). Symfony vrstva implementuje kontrakty definované doménou (repository interface, event dispatch) a zajišťuje HTTP, persistenci a messaging.

Směr závislostí je jednoznačný: Symfony závisí na doméně (implementuje její rozhraní), nikdy naopak. Doménová vrstva ze Symfony importuje jen Symfony\Component\Uid. Jedinou stopou infrastruktury v ní jsou mapovací atributy Doctrine (viz volba mappingu). Doctrine proto jde nahradit jiným ORM a Messenger jiným bus systémem bez zásahu do doménové logiky; přepíšou se jen metadata. Tento směr závislostí formalizuje hexagonální, onion i clean architektura. Jejich srovnání rozvádí kapitola o architektonických stylech.

10.02 Struktura projektu#

Výchozí struktura Symfony (src/Controller, src/Entity, src/Repository) řadí soubory podle technické role. Vertikální slice je řadí podle Bounded Contextu: každý kontext drží svou doménu, infrastrukturu i feature složky pohromadě. Odchylku připouštějí i Symfony Best Practices: doporučení výchozí struktury má dovětek „Unless your project follows a development practice that imposes a certain directory structure“ [1]. Příklad:

◢ Vzor

Příklad: Správná struktura projektu pro DDD s vertikální slice architekturou v Symfony 8

bash src/ (vertikální slice struktura)

1src/2├── UserManagement/             # Bounded Context: Správa uživatelů3│   ├── Domain/                 # Doménová vrstva pro UserManagement4│   │   ├── Model/              # Doménové modely5│   │   │   └── User.php6│   │   ├── ValueObject/        # Hodnotové objekty7│   │   │   ├── UserId.php8│   │   │   └── Email.php9│   │   ├── Event/              # Doménové události10│   │   │   └── UserRegistered.php11│   │   └── Repository/         # Repozitáře (rozhraní)12│   │       └── UserRepository.php13│   ├── Infrastructure/         # Infrastruktura pro UserManagement14│   │   └── Repository/         # Implementace repozitářů15│   │       └── DoctrineUserRepository.php16│   ├── Registration/           # Feature: Registrace uživatelů17│   │   ├── Command/            # Commands18│   │   │   ├── RegisterUser.php19│   │   │   └── RegisterUserHandler.php20│   │   ├── Controller/         # Controllers21│   │   │   ├── RegistrationController.php      # HTML formulář22│   │   │   └── RegistrationApiController.php   # JSON endpoint23│   │   ├── Form/               # Forms24│   │   │   └── RegistrationFormType.php25│   │   └── View/               # Views26│   │       └── registration.html.twig27│   └── Profile/                # Feature: Profil uživatele28│       ├── Query/              # Queries29│       │   ├── GetUserProfile.php30│       │   └── GetUserProfileHandler.php31│       ├── Controller/         # Controllers32│       │   └── ProfileController.php33│       ├── Form/               # Forms34│       │   └── ProfileFormType.php35│       └── View/               # Views36│           └── profile.html.twig37├── Ordering/           # Bounded Context: Správa objednávek38│   ├── Domain/                # Doménová vrstva pro Ordering39│   │   ├── Model/             # Doménové modely40│   │   │   ├── Order.php41│   │   │   └── OrderItem.php42│   │   ├── ValueObject/       # Hodnotové objekty43│   │   │   ├── OrderId.php44│   │   │   └── OrderStatus.php45│   │   ├── Event/             # Doménové události46│   │   │   └── OrderPlaced.php47│   │   └── Repository/        # Repozitáře (rozhraní)48│   │       └── OrderRepository.php49│   ├── Application/           # Aplikační vrstva pro Ordering50│   │   ├── Command/           # Commands51│   │   │   └── PlaceOrder.php52│   │   ├── Handler/           # Command handlery53│   │   │   └── PlaceOrderHandler.php54│   │   └── Query/             # Queries55│   │       ├── GetOrderHistory.php56│   │       └── GetOrderHistoryHandler.php57│   └── Infrastructure/        # Infrastruktura pro Ordering58│       ├── Repository/        # Implementace repozitářů59│       │   └── DoctrineOrderRepository.php60│       └── Http/              # Controllers61│           ├── CheckoutController.php62│           └── OrderHistoryController.php63└── SharedKernel/              # Skutečně sdílené komponenty64    ├── Domain/                # Sdílená doménová logika65    │   ├── AggregateRoot.php  # record() / releaseEvents()66    │   ├── Money.php          # Sdílený hodnotový objekt67    │   └── Currency.php       # Backed enum měn68    └── Infrastructure/        # Sdílená infrastruktura69        └── Persistence/       # Sdílené komponenty pro persistenci70            └── Doctrine/71                └── Mapping/72                    └── MappingTrait.php

Strom ukazuje obě organizace, které kniha používá. UserManagement řadí aplikační kód do feature složek, Ordering drží klasické vrstvy Domain/Application/Infrastructure. Kdy se vyplatí která, rozebírá Vertical Slice Architecture. Identifikátory nemají sdíleného předka: každý kontext má vlastní UserId nebo OrderId (důvod v Základních konceptech).

Závislosti mezi kontexty procházejí přes Application vrstvu nebo události, nikdy přes přímý import doménových tříd cizího kontextu. Výjimkou jsou jen identifikátory jako ShipmentId, které nenesou chování cizího modelu.

10.03 Implementace entit#

Do agregátu se vstupuje přes kořen agregátu. Třída dědí z bázové AggregateRoot, konstruktor je private a vznik probíhá přes pojmenovanou factory metodu (User::register(), Order::place()). Agregát tak nejde vytvořit v nekonzistentním stavu. Definice entity je v kapitole Základní koncepty DDD, zde jde o její podobu v Symfony.

◢ Vzor

Příklad: kořen agregátu User

php src/SharedKernel/Domain/AggregateRoot.php

1<?php2 3declare(strict_types=1);4 5namespace App\SharedKernel\Domain;6 7abstract class AggregateRoot8{9    /** @var list<object> */10    private array $domainEvents = [];11 12    final protected function record(object $event): void13    {14        $this->domainEvents[] = $event;15    }16 17    /** @return list<object> */18    final public function releaseEvents(): array19    {20        $events = $this->domainEvents;21        $this->domainEvents = [];22 23        return $events;24    }25}

php src/UserManagement/Domain/Model/User.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Model;6 7use App\SharedKernel\Domain\AggregateRoot;8use App\UserManagement\Domain\Event\UserRegistered;9use App\UserManagement\Domain\ValueObject\Email;10use App\UserManagement\Domain\ValueObject\HashedPassword;11use App\UserManagement\Domain\ValueObject\UserId;12use App\UserManagement\Domain\ValueObject\UserName;13use Doctrine\ORM\Mapping as ORM;14 15#[ORM\Entity]16#[ORM\Table(name: 'users')]17final class User extends AggregateRoot18{19    #[ORM\Id]20    #[ORM\Column(type: 'user_id')]21    public readonly UserId $id;22 23    #[ORM\Embedded(class: UserName::class)]24    private UserName $name;25 26    #[ORM\Column(type: 'email_vo', unique: true)]27    private Email $email;28 29    #[ORM\Embedded(class: HashedPassword::class)]30    private readonly HashedPassword $hashedPassword;31 32    #[ORM\Column(type: 'datetime_immutable')]33    public readonly \DateTimeImmutable $createdAt;34 35    #[ORM\Version]36    #[ORM\Column(type: 'integer')]37    private int $version = 1;38 39    private function __construct(40        UserId $id,41        UserName $name,42        Email $email,43        HashedPassword $hashedPassword,44    ) {45        $this->id = $id;46        $this->name = $name;47        $this->email = $email;48        $this->hashedPassword = $hashedPassword;49        $this->createdAt = new \DateTimeImmutable();50    }51 52    public static function register(53        UserId $id,54        UserName $name,55        Email $email,56        HashedPassword $hashedPassword,57    ): self {58        $user = new self($id, $name, $email, $hashedPassword);59        $user->record(new UserRegistered($id, $email, $user->createdAt));60 61        return $user;62    }63 64    public function name(): UserName65    {66        return $this->name;67    }68 69    public function email(): Email70    {71        return $this->email;72    }73 74    // Hash čte security vrstva při zakládání přihlašovacího záznamu.75    // Heslo v čitelné podobě agregát nezná a znát nemá.76    public function hashedPassword(): HashedPassword77    {78        return $this->hashedPassword;79    }80 81    public function rename(UserName $newName): void82    {83        if ($this->name->equals($newName)) {84            return;85        }86 87        $this->name = $newName;88    }89 90    public function changeEmail(Email $newEmail): void91    {92        if ($this->email->equals($newEmail)) {93            return;94        }95 96        $this->email = $newEmail;97    }98}

Detaily implementace:

final class User extends AggregateRoot. Bázová třída poskytuje record() a releaseEvents(), tedy sdílené chování pro všechny agregáty místo kopie v každé entitě. final mapované entitě nevadí: nativní lazy objekty z PHP 8.4 pracují nad původní třídou a žádnou podtřídu nevytvářejí [2], a DoctrineBundle 3 je už neumožňuje vypnout (rozbor v kapitole Návrh agregátu).
Privátní konstruktor + factory register(). Jediná povolená cesta, jak agregát vytvořit. Kdyby přibyla další kategorie (importovaný uživatel z LDAP), přidá se další factory, ne přepínač uvnitř konstruktoru. Událost UserRegistered se nahrává ve factory, ne v konstruktoru. Rekonstituce uloženého agregátu žádnou událost vyvolat nesmí. Doctrine při hydrataci konstruktor obchází, vlastní mapper (Persisted Object Pattern) ho ale přes reconstitute() volá.
VO uloženy přímo, ne jako primitivy. UserId, Email, UserName a HashedPassword jsou typy vlastností. Doctrine je hydratuje přes custom typy (user_id, email_vo) nebo #[ORM\Embedded]. Žádné re-validace v getterech.
#[ORM\Version] pro optimistický zámek. Souběžná modifikace agregátu skončí výjimkou OptimisticLockException, kterou aplikační vrstva přeloží na retry.
Názvy metod z Ubiquitous Language. rename() místo setName(), changeEmail() místo updateEmail(). Doménový jazyk, ne CRUD slovník.

10.04 Implementace hodnotových objektů#

V Symfony 8 se hodnotový objekt zapisuje jako final readonly PHP třída. Validace patří do konstruktoru, rovnost se počítá z hodnot, ne z identity. Detailní rozbor sémantiky VO je v kapitole Základní koncepty DDD:

◢ Vzor

Příklad: hodnotový objekt Email

php src/UserManagement/Domain/ValueObject/Email.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\ValueObject;6 7final readonly class Email8{9    public function __construct(10        public string $value,11    ) {12        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {13            throw new \InvalidArgumentException(14                sprintf('Invalid e-mail format: "%s".', $value),15            );16        }17    }18 19    public static function fromUserInput(string $raw): self20    {21        // Vstupy z formulářů normalizujeme zde (lowercase, trim).22        // Konstruktor hodnotu jen validuje a nemění – chrání invariant23        // „dvě instance se stejnou hodnotou jsou rovnocenné“.24        return new self(mb_strtolower(trim($raw)));25    }26 27    public function equals(self $other): bool28    {29        return $this->value === $other->value;30    }31 32    public function __toString(): string33    {34        return $this->value;35    }36}

HashedPassword má podobnou stavbu a jiný invariant – hodnotou je hash, ne heslo:

php src/UserManagement/Domain/ValueObject/HashedPassword.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\ValueObject;6 7use Doctrine\ORM\Mapping as ORM;8 9// Mapuje se přes #[ORM\Embedded], takže potřebuje atributy –10// stejně jako UserName o kus níž.11#[ORM\Embeddable]12final readonly class HashedPassword13{14    private function __construct(15        #[ORM\Column(length: 255)]16        public string $value,17    ) {}18 19    public static function fromPlainText(string $plain): self20    {21        if (strlen($plain) < 12) {22            throw new \InvalidArgumentException('Password must be at least 12 characters');23        }24 25        return new self(password_hash($plain, PASSWORD_DEFAULT));26    }27 28    /** Obnova z uloženého hashe (např. v mapperu) – hash se znovu nehashuje. */29    public static function fromHash(string $hash): self30    {31        return new self($hash);32    }33 34    public function matches(string $plain): bool35    {36        return password_verify($plain, $this->value);37    }38}

Konstruktor je tu privátní záměrně. new HashedPassword($plain) by uložil heslo v otevřené podobě a nic by se nestalo. Dvě pojmenované továrny ten omyl vylučují.

! Pozor

Limity `FILTER_VALIDATE_EMAIL`

PHP FILTER_VALIDATE_EMAIL ověřuje syntaxi addr-spec podle RFC 822, bez komentářů a zalamování bílých znaků. Drobnosti, které je dobré znát:

Odmítá i některé technicky platné adresy – a@b (doména bez tečky, např. user@localhost) neprojde, přestože RFC ji připouští.
Nepouští IDN domény (uživatel@české-domény.cz) bez explicitního převodu přes idn_to_ascii().
Neověřuje existenci schránky. Validní syntaxe ≠ doručitelná adresa.

Doménová vrstva tedy validuje jen syntaxi. Pravdivost potvrdí až e-mail s ověřovacím odkazem (out-of-band proces), který v doméně modeluje agregát EmailVerification nebo událost EmailVerificationRequested. Pro pokročilejší syntaktickou validaci existuje knihovna egulias/email-validator, o kterou se opírá omezení Assert\Email Symfony Validatoru v režimu strict.

◢ Vzor

Příklad: hodnotový objekt UserName s vlastními invarianty

php src/UserManagement/Domain/ValueObject/UserName.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\ValueObject;6 7use Doctrine\ORM\Mapping as ORM;8 9#[ORM\Embeddable]10final readonly class UserName11{12    public const MIN_LENGTH = 2;13    public const MAX_LENGTH = 100;14 15    #[ORM\Column(type: 'string', length: self::MAX_LENGTH)]16    public string $value;17 18    public function __construct(string $value)19    {20        $trimmed = trim($value);21        $length = mb_strlen($trimmed);22 23        if ($length < self::MIN_LENGTH || $length > self::MAX_LENGTH) {24            throw new \InvalidArgumentException(sprintf(25                'Name must be %d to %d characters long, got %d.',26                self::MIN_LENGTH,27                self::MAX_LENGTH,28                $length,29            ));30        }31 32        $this->value = $trimmed;33    }34 35    public function equals(self $other): bool36    {37        return $this->value === $other->value;38    }39 40    public function __toString(): string41    {42        return $this->value;43    }44}

UserName ukazuje, co hodnotový objekt přináší: invariant „jméno není prázdné a má rozumnou délku“ vynucuje typ. Volající kód nemá šanci vložit prázdný string. Pokud by to zkusil, dostane výjimku v konstruktoru, ne až v repozitáři. #[ORM\Embeddable] říká Doctrine, že VO se ukládá do sloupců tabulky vlastníka (žádná samostatná tabulka pro VO).

Třetí typ hodnotového objektu je identita agregátu. Generuje se v aplikaci, ne v databázi, takže handler zná ID ještě před uložením:

◢ Vzor

Příklad: UserId s generováním přes symfony/uid

php src/UserManagement/Domain/ValueObject/UserId.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\ValueObject;6 7use Symfony\Component\Uid\Uuid;8 9final readonly class UserId10{11    public function __construct(12        public string $value,13    ) {14        if (!Uuid::isValid($value)) {15            throw new \InvalidArgumentException(16                sprintf('Invalid UserId: "%s".', $value),17            );18        }19    }20 21    public static function generate(): self22    {23        return new self((string) Uuid::v7());24    }25 26    public static function fromString(string $value): self27    {28        return new self($value);29    }30 31    public function equals(self $other): bool32    {33        return $this->value === $other->value;34    }35 36    // Doctrine skládá klíč identity mapy přes implode() nad identifikátorem.37    // Bez __toString() padne už persist().38    public function __toString(): string39    {40        return $this->value;41    }42}

Uuid::v7() z balíčku symfony/uid vrací časově řaditelné UUID, vhodné jako primární klíč (sekvenční zápisy nedrobí B-tree index). Stejný vzor platí pro OrderId nebo PaymentId; hodnotu vždy zpřístupňuje public readonly property $value, žádná metoda value().

Property hooks a asymetrická viditelnost

Symfony 8 vyžaduje PHP 8.4, takže hodnotový objekt lze zapsat i jinak než přes readonly. Průvodce u něj přesto zůstává, a to ze dvou důvodů.

Asymetrická viditelnost (public private(set) string $value) nahrazuje dvojici privátní vlastnost plus getter. Hodí se objektům s wither metodami, které si uvnitř třídy potřebují hodnotu po clone přepsat. Pro hodnotový objekt je readonly přísnější: po inicializaci zakazuje jakýkoli zápis, i zevnitř třídy, takže neměnnost nestojí na disciplíně autora. Proto VO v celém průvodci zůstávají final readonly.

Property hooks svádějí přesunout validaci z konstruktoru do set hooku. U hodnotového objektu se to nevyplatí. Hook nejde kombinovat s readonly (PHP ohlásí „Hooked properties cannot be readonly“), takže by VO přišel o neměnnost. Při hydrataci Doctrine zapisuje surovou hodnotu přes ReflectionProperty::setRawValue() a hook obchází stejně jako konstruktor. Validace v hooku tedy nechrání nic, co by nechránil konstruktor.

10.05 Implementace repozitářů#

Repozitář se v Symfony 8 dělí na dvojici: rozhraní v doméně + Doctrine implementace v infrastruktuře. Doménový kód se opírá pouze o rozhraní, výměna persistence se odehraje v jediném souboru:

◢ Vzor

Příklad: Implementace repozitáře v Symfony 8

php src/UserManagement/Domain/Repository/UserRepository.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Repository;6 7use App\UserManagement\Domain\Model\User;8use App\UserManagement\Domain\ValueObject\Email;9use App\UserManagement\Domain\ValueObject\UserId;10 11interface UserRepository12{13    public function save(User $user): void;14 15    public function findById(UserId $id): ?User;16 17    public function findByEmail(Email $email): ?User;18}

php src/UserManagement/Infrastructure/Repository/DoctrineUserRepository.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Infrastructure\Repository;6 7use App\UserManagement\Domain\Model\User;8use App\UserManagement\Domain\Repository\UserRepository;9use App\UserManagement\Domain\ValueObject\Email;10use App\UserManagement\Domain\ValueObject\UserId;11use Doctrine\ORM\EntityManagerInterface;12 13final class DoctrineUserRepository implements UserRepository14{15    public function __construct(16        private readonly EntityManagerInterface $em,17    ) {}18 19    public function save(User $user): void20    {21        // Jen persist. Flush a commit vlastní doctrine_transaction middleware22        // command busu – repozitář transakci neřídí. Doménové události23        // (releaseEvents()) vyzvedne aplikační vrstva po flush(); co opouští24        // proces, jde přes Outbox Pattern (viz callouty níže).25        $this->em->persist($user);26    }27 28    public function findById(UserId $id): ?User29    {30        // Identifikátor se předává jako hodnotový objekt, ne jako řetězec:31        // custom typ převádí jen instanci UserId a na řetězec vyhodí32        // InvalidType (viz UserIdType v sekci o custom typech).33        return $this->em->find(User::class, $id);34    }35 36    public function findByEmail(Email $email): ?User37    {38        return $this->em->getRepository(User::class)39            ->findOneBy(['email' => $email]);40    }41}

DoctrineUserRepository implementuje doménové rozhraní UserRepository přes Doctrine ORM. save() jen zařadí agregát k uložení přes persist(); flush a commit provede transakční middleware na command busu, takže jeden use case odpovídá jedné transakci. Doménové události publikuje aplikační vrstva samostatným krokem až po flush(), aby posluchači viděli zapsaný stav.

! Pozor

Limit naivní publikace událostí

Nabízí se vypustit události hned po uložení agregátu: releaseEvents() a synchronní dispatch() v handleru. Posluchačům ve stejném procesu to stačí, běží uvnitř téže transakce. Potíž nastane, jakmile událost opouští proces. Dispatch před commitem ohlásí okolí registraci, kterou rollback ještě může zrušit. Dispatch až po commitu zase událost ztratí, když mezi oběma kroky proces spadne: OOM kill, deploy restart, výpadek brokera. Agregát pak v databázi je, ale z pohledu ostatních kontextů se registrace neudála. Pro vývoj a méně důležité události je to přijatelné. Jakmile na události závisí jiný Bounded Context nebo platební tok, produkčním řešením je Outbox Pattern. Událost se zapíše do stejné DB transakce jako agregát a samostatný worker ji doručí s retry. Detail v kapitole Outbox Pattern.

! Pozor

Dvojí transakce: repozitář vs. middleware

Nabízí se obalit tělo save() ještě vlastní transakcí přes wrapInTransaction(). Pokud ale command bus používá doctrine_transaction middleware (viz aplikační služby), vzniknou dvě vrstvy transakcí: middleware otevře vnější, repozitář vnitřní přes savepoint. Commit point přestane být zřejmý a rollback vnitřní vrstvy nezruší vnější zápisy. Transakci má řídit jediná vrstva. Doporučenou volbou je middleware na command busu, který obalí celý handler, zavolá flush() a commitne. Repozitář pak jen volá persist(), transakci ani flush neřídí.

S middlewarem se mění i okamžik commitu: flush() zapíše SQL, commit provede až middleware po doběhnutí handleru. Synchronní dispatch v handleru tedy běží uvnitř otevřené transakce. Posluchačům v témže procesu to nevadí, rollback vrátí i jejich zápisy. Vedlejší efekty mimo proces (e-mail, broker) by ale reagovaly na událost, která se nikdy nestala. Ty patří do Outboxu, kde se událost commituje spolu s agregátem.

Doručení za commit posune stamp DispatchAfterCurrentBusStamp, pokud middleware dispatch_after_current_bus stojí před doctrine_transaction (rozbor). Riziko ztráty události při pádu procesu tím ale nezmizí.

10.06 Persisted Object Pattern – oddělený persistence model#

Doménová vrstva bez jediného kusu metadat o persistenci vyžaduje druhý objektový model. Doménová třída zůstane POPO bez atributů, vedle ní v infrastrukturní vrstvě žije samostatná persistence třída se všemi Doctrine atributy a mapper mezi nimi překládá oběma směry. Průvodce pro tuto konstrukci používá název Persisted Object Pattern; v literatuře se pro ni vžilo označení persistence model a obecným rodičovským vzorem je Fowlerův Data Mapper (PoEAA, 2002) [4].

Dva nejčastěji citovaní obhájci čisté domény jsou přitom proti. Vladimir Khorikov označuje plnohodnotný persistence model za příliš drahý. Složitost roste s každou asociací typu one-to-many a many-to-many. Navíc se ztrácí ORM change tracking, o který se opírají spolehlivé doménové události [5]. Matthias Noback nazývá oddělené entity „expensive and unnecessary form of decoupling“ a doporučuje místo nich ORM entitu obohacenou o doménové metody, invarianty a vlastní výjimky [6]. Jediný scénář, který uznává, je vývoj návrhu agregátů nezávisle na schématu databáze. Sám s ním podle svých slov zkušenost nemá a projekty s oddělenými entitami, o kterých slyšel, takovou potřebu neměly.

Sekce v průvodci zůstává proto, že ukazuje, co taková separace stojí. Ukázka je úplná, ať si tu cenu můžete spočítat sami.

◢ Vzor

Příklad: doména POPO + persistence model + mapper

php src/UserManagement/Domain/Model/User.php (POPO – bez atributů)

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Model;6 7use App\SharedKernel\Domain\AggregateRoot;8use App\UserManagement\Domain\ValueObject\Email;9use App\UserManagement\Domain\ValueObject\HashedPassword;10use App\UserManagement\Domain\ValueObject\UserId;11use App\UserManagement\Domain\ValueObject\UserName;12 13final class User extends AggregateRoot14{15    private function __construct(16        public readonly UserId $id,17        private UserName $name,18        private Email $email,19        private readonly HashedPassword $hashedPassword,20        public readonly \DateTimeImmutable $createdAt,21    ) {}22 23    public static function register(/* ... */): self { /* ... */ }24    public static function reconstitute(25        UserId $id,26        UserName $name,27        Email $email,28        HashedPassword $hashedPassword,29        \DateTimeImmutable $createdAt,30    ): self {31        // Speciální factory pro mapper – obnovuje agregát z perzistovaného stavu32        // a žádnou doménovou událost nezaznamená.33        return new self($id, $name, $email, $hashedPassword, $createdAt);34    }35 36    // doménové operace ...37}

php src/UserManagement/Infrastructure/Persistence/Doctrine/UserPersistenceModel.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Infrastructure\Persistence\Doctrine;6 7use Doctrine\ORM\Mapping as ORM;8 9#[ORM\Entity]10#[ORM\Table(name: 'users')]11class UserPersistenceModel12{13    #[ORM\Id]14    #[ORM\Column(type: 'string', length: 36)]15    public string $id;16 17    #[ORM\Column(type: 'string', length: 100)]18    public string $name;19 20    #[ORM\Column(type: 'string', length: 255, unique: true)]21    public string $email;22 23    #[ORM\Column(type: 'string', length: 255)]24    public string $passwordHash;25 26    #[ORM\Column(type: 'datetime_immutable')]27    public \DateTimeImmutable $createdAt;28 29    #[ORM\Version]30    #[ORM\Column(type: 'integer')]31    public int $version = 1;32}

php src/UserManagement/Infrastructure/Persistence/Doctrine/UserMapper.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Infrastructure\Persistence\Doctrine;6 7use App\UserManagement\Domain\Model\User;8use App\UserManagement\Domain\ValueObject\Email;9use App\UserManagement\Domain\ValueObject\HashedPassword;10use App\UserManagement\Domain\ValueObject\UserId;11use App\UserManagement\Domain\ValueObject\UserName;12 13final class UserMapper14{15    public function toDomain(UserPersistenceModel $row): User16    {17        return User::reconstitute(18            new UserId($row->id),19            new UserName($row->name),20            new Email($row->email),21            HashedPassword::fromHash($row->passwordHash),22            $row->createdAt,23        );24    }25 26    public function toPersistence(User $user): UserPersistenceModel27    {28        $model = new UserPersistenceModel();29        $model->id = $user->id->value;30        $model->name = (string) $user->name();31        $model->email = $user->email()->value;32        $model->passwordHash = $user->hashedPassword()->value;33        $model->createdAt = $user->createdAt;34 35        return $model;36    }37}

§ Poznámka

Cena čisté varianty

Persisted Object Pattern drží doménu úplně mimo ORM: nemá žádný atribut ani use Doctrine\…. Cena:

2× kód. Doménová třída + persistence model + mapper. Pro každý agregát.
Mapování VO ručně. Custom typy z hlavní cesty zde nepoužijete; převod obstará mapper. U 5+ VO se kód mapperu rozrůstá.
Riziko driftu. Když přibude pole v doméně, musí přibýt v persistence modelu i v mapperu. Překladač to nehlídá.
Optimistický zámek je řešení navíc. #[ORM\Version] je v persistence modelu; doména User musí přijmout version jako parametr reconstitute(), nebo se spolehnout na infrastrukturu, že verzi sleduje sama.
Update vyžaduje find-and-copy. toPersistence() výše vytváří novou instanci s version = 1, a to pro insert stačí. Při update musí repozitář nejprve načíst existující UserPersistenceModel a přepsat její pole; nová instance by kolidovala s primárním klíčem a vynulovala optimistický zámek.

Persisted Object se vyplatí jen v kontextech, kde na oddělení skutečně záleží (Core Domain s vysokou hodnotou, dlouhodobá údržba, plán na výměnu persistence). Pro většinu Bounded Contextů jsou atributy přijatelný kompromis.

Ruční mapper je největší nákladová položka vzoru a od Symfony 7.4 na něj existuje stabilní komponenta symfony/object-mapper [7]. Atribut #[Map(target: UserPersistenceModel::class)] popíše převod deklarativně, ObjectMapperInterface::map() ho provede. Ruční kód pak zbude jen tam, kde se tvar obou modelů rozchází, typicky u hodnotových objektů složených z více sloupců. Riziko driftu tím ale nezmizí: komponenta přemapuje to, co jí popíšete, a chybějící pole nenahlásí.

Další příklady průvodce zůstávají u atributů přímo na agregátech a Persisted Object Pattern dál nerozvádějí. Principy jsou stejné, jen každý agregát potřebuje vlastní mapper.

10.07 Doctrine custom types pro Value Objects#

Sekce Implementace entit deklaruje vlastnosti přímo typu Email nebo UserId. Jejich hydrataci zajišťuje Doctrine custom type, konvertor mezi databázovým primitivem a hodnotovým objektem.

◢ Vzor

Příklad: Doctrine custom type pro Email

php src/UserManagement/Infrastructure/Doctrine/Type/EmailType.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Infrastructure\Doctrine\Type;6 7use App\UserManagement\Domain\ValueObject\Email;8use Doctrine\DBAL\Platforms\AbstractPlatform;9use Doctrine\DBAL\Types\StringType;10 11final class EmailType extends StringType12{13    public const NAME = 'email_vo';14 15    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): ?Email16    {17        if ($value === null) {18            return null;19        }20 21        return new Email((string) $value);22    }23 24    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): ?string25    {26        if ($value === null) {27            return null;28        }29 30        return $value instanceof Email ? $value->value : (string) $value;31    }32 33    /** @param array<string, mixed> $column */34    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string35    {36        return $platform->getStringTypeDeclarationSQL(['length' => 255]);37    }38}

UserIdType se registruje ve stejné konfiguraci. Výpis je celý kvůli detailu, který se často přehlédne: na rozdíl od tolerantního EmailType musí převod identifikátoru selhat hlasitě. Kdyby na neočekávaný vstup vracel null, dotaz by tiše nic nenašel:

php src/UserManagement/Infrastructure/Doctrine/Type/UserIdType.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Infrastructure\Doctrine\Type;6 7use App\UserManagement\Domain\ValueObject\UserId;8use Doctrine\DBAL\Platforms\AbstractPlatform;9use Doctrine\DBAL\Types\Exception\InvalidType;10use Doctrine\DBAL\Types\StringType;11 12final class UserIdType extends StringType13{14    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): ?UserId15    {16        return $value === null ? null : UserId::fromString((string) $value);17    }18 19    public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): ?string20    {21        if ($value === null || $value instanceof UserId) {22            return $value?->value;23        }24 25        throw InvalidType::new($value, self::class, ['null', UserId::class]);26    }27 28    public function getSQLDeclaration(array $column, AbstractPlatform $platform): string29    {30        return $platform->getStringTypeDeclarationSQL(['length' => 36, 'fixed' => true]);31    }32}

◢ Vzor

Registrace custom type v Symfony

yaml config/packages/doctrine.yaml (výřez)

1# Klíče se přilévají k `types:` z kapitoly o agregátech, kde už leží2# order_id, customer_id a product_id. Zápis `název: Třída` a3# `název: { class: Třída }` znamená totéž; míchat je v jednom souboru4# nevadí, nahradit jeden blok druhým ale znamená přijít o půlku typů.5doctrine:6    dbal:7        types:8            email_vo: App\UserManagement\Infrastructure\Doctrine\Type\EmailType9            user_id:  App\UserManagement\Infrastructure\Doctrine\Type\UserIdType

php src/UserManagement/Domain/Model/User.php (použití typu)

1// Atribut odkazuje na registrovaný typ jménem:2#[ORM\Column(type: 'email_vo', unique: true)]3private Email $email;

Proč oba typy nemají metodu getName(), vysvětluje Návrh agregátu. Konstanta NAME je jen pojmenovaná reference, kterou lze v atributu #[ORM\Column] použít místo řetězce. Bez getSQLDeclaration() by délku sloupce diktoval rodičovský StringType.

XML mapping (User.orm.xml) dokáže totéž bez atributů ve třídě, doménu od ORM ale neoddělí, jen přesune metadata do jiného formátu. Po odstranění annotation a YAML driveru v ORM 3 zbývá vedle atributů jen XML a málo používané PHP mapování [8]. Nástroje kolem Doctrine obě varianty obsluhují hůř než atributy. Kdo chce striktní oddělení, najde řešení v sekci Persisted Object Pattern.

10.08 Enums pro stavové typy#

Stav objednávky, role uživatele, priorita úkolu. Konečné množiny hodnot, které se dřív modelovaly konstantami ve třídě, mají nativní typ: enum. Překlep v názvu case odhalí statická analýza, neznámou hodnotu odmítne typová kontrola za běhu.

◢ Vzor

Příklad: Backed enum pro stav objednávky

php src/Ordering/Domain/ValueObject/OrderStatus.php

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\ValueObject;6 7enum OrderStatus: string8{9    case Draft = 'draft';10    case Confirmed = 'confirmed';11    case Paid = 'paid';12    case Shipped = 'shipped';13    case Delivered = 'delivered';14    case Cancelled = 'cancelled';15 16    /**17     * Vrátí stavy, do kterých je možné z aktuálního stavu přejít.18     *19     * @return self[]20     */21    public function allowedTransitions(): array22    {23        return match ($this) {24            self::Draft => [self::Confirmed, self::Cancelled],25            self::Confirmed => [self::Paid, self::Cancelled],26            self::Paid => [self::Shipped, self::Cancelled],27            // Odeslanou zásilku storno nevrátí; od tohoto bodu se situace28            // řeší kompenzací v sáze, ne přechodem agregátu.29            self::Shipped => [self::Delivered],30            self::Delivered => [],31            self::Cancelled => [],32        };33    }34 35    public function canTransitionTo(self $target): bool36    {37        return in_array($target, $this->allowedTransitions(), true);38    }39}

◢ Vzor

Příklad: Použití enum v doménové entitě

php src/Ordering/Domain/Model/Order.php (alternativa: transitionTo)

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\Model;6 7use App\Ordering\Domain\Event\OrderPlaced;8use App\Ordering\Domain\Event\OrderStatusChanged;9use App\Ordering\Domain\Exception\InvalidOrderStateTransitionException;10use App\Ordering\Domain\ValueObject\CustomerId;11use App\Ordering\Domain\ValueObject\OrderId;12use App\Ordering\Domain\ValueObject\OrderStatus;13use App\SharedKernel\Domain\AggregateRoot;14 15final class Order extends AggregateRoot16{17    private OrderStatus $status;18    private readonly \DateTimeImmutable $createdAt;19 20    private function __construct(21        public readonly OrderId $id,22        public readonly CustomerId $customerId,23    ) {24        $this->status = OrderStatus::Draft;25        $this->createdAt = new \DateTimeImmutable();26    }27 28    public static function place(OrderId $id, CustomerId $customerId): self29    {30        $order = new self($id, $customerId);31        $order->record(new OrderPlaced($id, $customerId));32 33        return $order;34    }35 36    // Getter drží výřez krátký; kanonický Order čte stav přes37    // public private(set), viz kapitola Návrh agregátu.38    public function status(): OrderStatus39    {40        return $this->status;41    }42 43    public function transitionTo(OrderStatus $newStatus): void44    {45        if (!$this->status->canTransitionTo($newStatus)) {46            throw InvalidOrderStateTransitionException::cannotTransition(47                $this->status->value,48                $newStatus->value,49            );50        }51 52        $oldStatus = $this->status;53        $this->status = $newStatus;54 55        $this->record(new OrderStatusChanged(56            $this->id,57            $oldStatus,58            $newStatus,59            new \DateTimeImmutable(),60        ));61    }62}

php src/Ordering/Domain/Event/OrderStatusChanged.php

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\Event;6 7use App\Ordering\Domain\ValueObject\OrderId;8use App\Ordering\Domain\ValueObject\OrderStatus;9 10final readonly class OrderStatusChanged11{12    public function __construct(13        public OrderId $orderId,14        public OrderStatus $from,15        public OrderStatus $to,16        public \DateTimeImmutable $occurredAt,17    ) {}18}

transitionTo() je alternativa k pojmenovaným přechodům, ne jejich doplněk. Kanonický agregát z Návrhu agregátu používá markPaid(), ship() a cancel(), protože každá operace nese vlastní invariant a vlastní událost. OrderPaid říká víc než OrderStatusChanged(Confirmed, Paid). Kdo si nechá obojí, dostane dvě cesty do téhož stavu, které zaznamenají různé události: markPaid() vydá OrderPaid, transitionTo() vydá OrderStatusChanged. Projekce, která poslouchá jen jednu z nich, pak podle toho, kudy se šlo, změnu jednou vidí a jednou ne.

Obecný přechod se vyplatí tam, kde je stavů hodně, přechody jsou jednotvárné a odlišné události by nic nepřinesly: workflow tiketu, stavy dokumentu ve schvalování. Objednávka mezi takové případy nepatří.

§ Poznámka

Kdy použít enum a kdy plnohodnotný hodnotový objekt?

Enum – pro jednoduché konečné stavy, kde hodnota je jedna z pevně daných variant: OrderStatus, UserRole, TaskPriority, Currency. Enums podporují metody, takže lze zapouzdřit i přechodovou logiku (viz allowedTransitions()).
Plnohodnotný hodnotový objekt (Value Object) – pro typy s vlastní validací, formátováním nebo aritmetikou. Třeba Money (částka, měna, zaokrouhlování), Email (validace formátu), Address (více polí) nebo DateRange (interval s logikou překrývání).

Obecné pravidlo: typ s konečným, předem známým počtem hodnot a bez složité vnitřní logiky je enum. Libovolné hodnoty, validace nebo výpočty vedou k hodnotovému objektu.

10.09 Doménové služby (a kdy je nepoužít)#

Doménová služba zapouzdřuje pravidlo, které přirozeně nepatří žádnému agregátu ani hodnotovému objektu. Typicky jde o operaci nad dvěma a více agregáty (MoneyTransferService mezi dvěma účty) nebo o bezstavový výpočet s externím vstupem: kurzovní převod, kalkulace daně podle jurisdikce.

Před sáhnutím po doménové službě stojí vždy jedna otázka: nepatří to do agregátu? Pravidlo „lze platit jen potvrzenou objednávku“ je čistý invariant agregátu Order. Jen Order zná svůj stav a jen on ho smí měnit. Doménová služba na tomtéž místě je anti-vzor: oslabuje agregát a vede k anemickému modelu.

✕ Anti-vzor

Anti-vzor: doménová služba pro invariant jednoho agregátu

php src/Ordering/Domain/Service/PaymentService.php (ANTI-VZOR)

1<?php2 3// ANTI-VZOR: pravidlo „lze platit jen potvrzenou objednávku“ je invariant4// agregátu Order, ne odpovědnost externí služby.5final class PaymentService6{7    public function processPayment(Order $order, Money $amount, PaymentMethod $pm): Payment8    {9        if ($order->status() !== OrderStatus::Confirmed) {10            throw new \DomainException('Cannot process payment for a non-confirmed order');11        }12 13        return new Payment(PaymentId::generate(), $order->id, $amount, $pm);14    }15}

Co se tu pokazilo:

Invariant uniká agregátu. Order neví, že někdo kontroluje jeho stav zvenčí. Přibude-li stav Refunded, oprava míří do služby, ne do agregátu.
Anemický model. Getter status() tu neslouží čtenáři, ale cizí třídě, která za Order rozhoduje o jeho vlastním přechodu.
Otevřená cesta k inkonzistenci. Nikdo nezabrání druhé službě, aby obešla pravidlo a vytvořila Payment přímo.

◢ Vzor

Správně: invariant uvnitř agregátu, factory metoda na výsledek

php src/Ordering/Domain/Model/Order.php (alternativa: recordPayment)

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\Model;6 7use App\Ordering\Domain\Event\PaymentRecorded;8use App\Ordering\Domain\Exception\InvalidOrderStateTransitionException;9use App\Ordering\Domain\ValueObject\OrderStatus;10use App\Ordering\Domain\ValueObject\PaymentId;11use App\Ordering\Domain\ValueObject\PaymentMethod;12use App\SharedKernel\Domain\AggregateRoot;13use App\SharedKernel\Domain\Money;14 15final class Order extends AggregateRoot16{17    // ... id, status, items, factory method `place()` viz dříve ...18 19    public function recordPayment(Money $amount, PaymentMethod $method): Payment20    {21        if ($this->status !== OrderStatus::Confirmed) {22            throw InvalidOrderStateTransitionException::cannotTransition(23                $this->status->value,24                OrderStatus::Paid->value,25            );26        }27 28        if (!$amount->equals($this->totalAmount())) {29            // Přiznaná zkratka – plný model zde hází pojmenovanou výjimku.30            throw new \DomainException('Payment amount does not match order total.');31        }32 33        $this->status = OrderStatus::Paid;34 35        $payment = Payment::forOrder($this->id, $amount, $method);36 37        $this->record(new PaymentRecorded($this->id, $payment->id(), $amount));38 39        return $payment;40    }41}

Order::recordPayment() zapouzdřuje pravidlo i přechod stavu uvnitř agregátu. Jediný způsob, jak pro objednávku vytvořit Payment, vede přes tuto metodu.

Ukázka je ilustrativní varianta k markPaid() z Návrhu agregátu a stojí na čtyřech třídách, které kniha dál nerozvádí: Payment, PaymentId, PaymentMethod a PaymentRecorded. Kanonický model platbu jako samostatný agregát nemodeluje; má ji v kontextu Payment za hranicí, kam se posílá příkaz. Do projektu podle knihy proto patří markPaid(); tento výpis ukazuje jen alternativu, kde platba vzniká uvnitř objednávky. Invariant „platit lze jen potvrzenou objednávku“ tak vynucuje agregát sám, ne naděje, že někdo zavolá správnou službu. Aplikační handler pak má jen koordinační roli. Pojmy command a handler vysvětluje sekce o aplikačních službách, podrobně kapitola CQRS:

◢ Vzor

Aplikační handler nad agregátem

php src/Ordering/Application/Handler/RecordPaymentHandler.php

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Application\Handler;6 7use App\Ordering\Application\Command\RecordPayment;8use App\Ordering\Domain\Repository\OrderRepository;9use App\Ordering\Domain\Repository\PaymentRepository;10use App\SharedKernel\Domain\Currency;11use App\SharedKernel\Domain\Money;12use App\Ordering\Domain\ValueObject\OrderId;13use App\Ordering\Domain\ValueObject\PaymentMethod;14use Symfony\Component\Messenger\Attribute\AsMessageHandler;15 16#[AsMessageHandler(bus: 'command.bus')]17final class RecordPaymentHandler18{19    public function __construct(20        private readonly OrderRepository $orders,21        private readonly PaymentRepository $payments,22    ) {}23 24    public function __invoke(RecordPayment $cmd): void25    {26        $order = $this->orders->get(OrderId::fromString($cmd->orderId));27 28        $payment = $order->recordPayment(29            new Money($cmd->amountInCents, Currency::from($cmd->currency)),30            PaymentMethod::from($cmd->method),31        );32 33        $this->orders->save($order);34        $this->payments->save($payment);35    }36}

Handler zapisuje dva agregáty v jedné transakci. Je to odchylka od vodítka jeden agregát na transakci a žádná z Vernonových výjimek ji nekryje. Rozpad na dvě transakce by sice připustil zaplacenou objednávku bez platby, jenže invariant sdílený dvěma agregáty je podle Khononova signál, že hranice mezi Order a Payment stojí jinde. Ukázka odchylku drží kvůli jednoduchosti; kanonický model proto platbu nechává v kontextu Payment a objednávce posílá jen markPaid(). Alternativou uvnitř jednoho kontextu je eventual consistency: Order zaznamená PaymentRecorded a Payment vzniká až v reakci na událost. Cena je okno, kdy platba ještě neexistuje, a nutnost kompenzace při selhání.

§ Poznámka

Kdy doménová služba opravdu dává smysl

Doménová služba je správná volba ve třech přesně vymezených případech:

Operace nad 2+ agregáty. Klasický MoneyTransferService::transfer($from, $to, $amount). Pravidlo „součet zůstatků je konstantní“ se týká dvou účtů a nepatří jednomu ani druhému. Služba mění oba účty. Uložit je jednou transakcí je vědomé porušení vodítka jeden agregát na transakci; bez výjimky převod rozloží sága (viz Doplňující taktické vzory).
Bezstavový výpočet s externí znalostí. Daňová sazba podle jurisdikce a typu zboží, převod měn podle aktuálního kurzu. Logika je čistě doménová, ale vstupy přicházejí zvenčí.
Generická doménová operace bez přirozeného vlastníka. „Vyčisti expirované rezervace starší než X dnů“. Akce nad množinou agregátů, kde žádný z nich není přirozený vlastník pravidla.

Ve všech ostatních případech patří pravidlo do agregátu, hodnotového objektu nebo specifikace (Specification Pattern).

10.10 Specification Pattern#

Specification Pattern (Eric Evans, DDD, kap. 9) zapouzdřuje doménové pravidlo do samostatného objektu s metodou isSatisfiedBy(). Pravidlo „objednávka je způsobilá k expedici“ pak existuje na jednom místě. Táž specifikace slouží validaci v agregátu, filtrování kolekcí i výběru v repozitáři. Malá pravidla se skládají kombinátory and(), or() a not() do složitějších, bez kopírování podmínek po kódu.

Plný výklad včetně implementace v PHP, kombinátorů a napojení na Doctrine na Doctrine najdete v kapitole Specification Pattern.

10.11 Implementace doménových událostí#

Doménová událost je fakt minulého času: registrace proběhla, platba byla zaznamenána. Kód ji v Symfony 8 modeluje jako neměnnou PHP třídu, kterou agregát zaznamená při změně stavu:

◢ Vzor

Příklad: Implementace doménové události v Symfony 8

php src/UserManagement/Domain/Event/UserRegistered.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Event;6 7use App\UserManagement\Domain\ValueObject\Email;8use App\UserManagement\Domain\ValueObject\UserId;9 10final readonly class UserRegistered11{12    public string $userId;13    public string $email;14 15    public function __construct(16        UserId $userId,17        Email $email,18        public \DateTimeImmutable $occurredAt,19    ) {20        // Událost nese primitivy – serializuje se bez závislosti na VO třídách.21        $this->userId = $userId->value;22        $this->email = $email->value;23    }24}

UserRegistered nese minimum potřebné pro obnovu kontextu: ID uživatele, e-mail a čas registrace. Na rozdíl od událostí objednávky, které nesou hodnotové objekty (viz Návrh agregátu), jsou to primitivy. Událost odebírá i kontext Identity (Autorizace v DDD), a proto má tvar integrační události. Listenery i externí konzumenti z těchto tří hodnot poskládají reakci, aniž by sahali zpět do UserRepository. Konstruktor odpovídá volání record(new UserRegistered(...)) ve factory User::register() v sekci Implementace entit.

§ Poznámka

Symfony EventDispatcher vs. Messenger pro doménové události

Symfony nabízí dva mechanismy pro „něco se stalo“:

EventDispatcher (EventDispatcherInterface) – synchronní, in-process. Listenery se provedou okamžitě v témž PHP požadavku, ve sdíleném paměťovém prostoru. Bez serializace, bez síťové cesty tam a zpět.
Messenger (MessageBusInterface) – může být synchronní i asynchronní. Podporuje transporty (RabbitMQ, Redis, databáze přes Doctrine), retry strategii a serializaci zprávy. Příjemce může běžet v jiném procesu i na jiném serveru. Transport lze určit atributem #[AsMessage(transport: 'async_events')] přímo na třídě zprávy; konfigurace framework.messenger.routing má nad atributem přednost, takže per-environment override zůstává možný [9].

Volba podle role příjemce:

Posluchači uvnitř kontextu (read model téhož kontextu, audit log, invalidace cache) → synchronní event.bus v Messengeru. Posluchač běží v témž požadavku a pod middlewarem doctrine_transaction i v téže transakci. Takto události odesílá handler registrace.
Komunikace přes hranici kontextu (událost zpracuje jiný kontext nebo služba) → Messenger s asynchronním transportem. Zpráva dorazí do brokera a jiný kontext si ji odebere. Spolehlivé doručení zajišťuje v produkci Outbox Pattern.
Technické háčky frameworku (kernel eventy, události Security a formulářů) patří EventDispatcheru. Doménové události jím neprocházejí.

Jedna sběrnice pro doménové události má praktický důvod. Přesun posluchače ze synchronního zpracování na asynchronní je pak změna routingu v konfiguraci, ne přepis kódu. Asynchronní transport ovšem něco stojí: serializaci každé zprávy, ztrátu společné transakce a správu transportů navíc. O transportu proto rozhoduje hranice, kterou událost překračuje, ne hypotetická budoucí potřeba.

! Pozor

Proč ne Doctrine lifecycle listener

Třetí cesta, kterou v Symfony projektech potkáte často: Doctrine listener (#[AsDoctrineListener]) na onFlush nebo postFlush, který si sám vybere agregáty a vypustí jejich události. Vypadá to jako úspora: aplikační vrstva o publikaci nemusí vědět. Obě události ale mají omezení, která se projeví až v provozu.

V onFlush už Doctrine spočítal changesety, takže samotný persist() nového objektu se do právě probíhajícího flushe nepromítne; dovolat se musí UnitOfWork::computeChangeSet(), respektive recomputeSingleEntityChangeSet(). V postFlush zase nelze bezpečně zavolat flush(); rekurze do právě dokončeného flushe končí nedefinovaným chováním. Publikace událostí se tak ocitá v kódu, který má nejtěsnější vazbu na vnitřnosti ORM a nejhůř se testuje. Obě omezení popisuje dokumentace Doctrine [10]. Explicitní dispatch v aplikační vrstvě (nebo Outbox) je proto v tomto průvodci výchozí volba.

10.12 Strategie zpracování chyb v DDD#

V DDD se výjimky liší podle vrstvy, ve které vznikají. Každá vrstva má jiné odpovědnosti a jiný typ chyb:

§ Poznámka

Typy výjimek podle vrstvy

Doménové výjimky – porušení doménových pravidel a invariantů. Vyhazuje je doménový model (entity, agregáty, value objects). Příklady: InvalidOrderStateTransitionException, InsufficientFundsException, DuplicateEmailException. Patří sem i OrderNotFoundException: chybějící agregát je chyba v jazyce domény, výjimka proto leží v Domain\Exception a hází ji repozitář z get().
Aplikační výjimky – chyby use case, které neporušují doménové pravidlo: neplatný vstup commandu nebo chybějící oprávnění. Vznikají v handlerech a v middleware sběrnice. Příklad: ValidationFailedException z middlewaru validation.
Infrastrukturní výjimky – technické chyby (databáze, síť, souborový systém). Vznikají v infrastrukturní vrstvě a zachytává je aplikační vrstva. Příklady: ConnectionException, TimeoutException.

◢ Vzor

Příklad: Vlastní doménová výjimka

php src/Ordering/Domain/Exception/InvalidOrderStateTransitionException.php

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\Exception;6 7/**8 * Výjimka vyhazovaná při porušení pravidel přechodu stavu objednávky.9 */10final class InvalidOrderStateTransitionException extends \DomainException11{12    public static function cannotTransition(string $from, string $to): self13    {14        return new self(sprintf(15            'Cannot transition from "%s" to "%s".',16            $from,17            $to,18        ));19    }20 21    /** Ne každé porušení je přechod – přidání položky mimo Draft také ne. */22    public static function notAllowedInState(string $operation, string $state): self23    {24        return new self(sprintf(25            'Operation "%s" is not allowed in state "%s".',26            $operation,27            $state,28        ));29    }30}

Ve stejném duchu vznikají ostatní doménové výjimky, které kniha používá. Všechny dědí z \DomainException a pojmenovaná továrna nese formulaci chyby, aby se text hlášky neopakoval na každém throw:

php src/Ordering/Domain/Exception/EmptyOrderException.php + OrderNotFoundException.php

1<?php2 3declare(strict_types=1);4 5namespace App\Ordering\Domain\Exception;6 7use App\Ordering\Domain\ValueObject\OrderId;8 9final class EmptyOrderException extends \DomainException10{11    public static function cannotConfirm(): self12    {13        return new self('Cannot confirm an order without items.');14    }15 16    public static function cannotBePlaced(): self17    {18        return new self('Order must contain at least one item.');19    }20}21 22final class OrderNotFoundException extends \DomainException23{24    public static function withId(OrderId $id): self25    {26        return new self(sprintf('Order "%s" not found.', $id->value));27    }28}

UserManagement má vlastní rodinu se stejnou stavbou. DuplicateEmailException s továrnou with(Email $email) je definovaná u handleru registrace. Zbylé dvě chrání aktivaci účtu a obě mají továrnu forUser(UserId $id):

php src/UserManagement/Domain/Exception/UserAlreadyActivatedException.php + InvalidVerificationTokenException.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Exception;6 7use App\UserManagement\Domain\ValueObject\UserId;8 9final class UserAlreadyActivatedException extends \DomainException10{11    public static function forUser(UserId $id): self12    {13        return new self(sprintf('User "%s" is already activated.', $id->value));14    }15}16 17// --- src/UserManagement/Domain/Exception/InvalidVerificationTokenException.php ---18 19final class InvalidVerificationTokenException extends \DomainException20{21    public static function forUser(UserId $id): self22    {23        return new self(sprintf('Verification token for user "%s" does not match.', $id->value));24    }25}

Kanonický User z této kapitoly aktivaci nemá. Obě výjimky použije až rozšířený aktivační model s VerificationToken v kapitolách Migrace z CRUD na DDD a Anti-vzory a typické chyby.

! Pozor

Doporučení pro výjimky v DDD

Vlastní bázová třída nebo marker interface na kontext (UserManagementException) umožní chytit „všechny doménové chyby tohoto kontextu“ jedním catch. SPL \DomainException je potomek \LogicException, tedy podle sémantiky SPL chyba programátora, ne očekávaný běhový stav; ukázky v tomto průvodci z něj dědí jako přiznanou zkratku.
Statické factory metody (cannotTransition()) drží vytváření výjimek čitelné a konzistentní.
Infrastrukturní výjimky se do doménové vrstvy nepropagují. Repozitář je zachytí a přeloží na doménové.
Překlad doménové výjimky na HTTP odpověď (400, 404, 409) patří na jedno místo. Kontroler ho zvládne u jednoho use case; napříč aplikací se vyplatí ExceptionListener nebo atribut #[WithHttpStatus] na doménové výjimce. Rozbor v sekci o kontrolerech.

10.13 Implementace aplikačních služeb#

Trojice command, handler a bus se zde objevuje poprvé, proto krátce k pojmům. Command je neměnný objekt popisující záměr: „zaregistruj uživatele s tímto jménem a e-mailem“. Nemá chování, nese jen data use case. Handler je třída, která command vykoná: načte agregáty, zavolá doménovou metodu, uloží výsledek.

Command bus oba spojuje. Volající předá command busu (MessageBusInterface ze Symfony Messenger) a ten najde příslušný handler podle typu zprávy. Mezi dispatch a handler se navíc vkládají middleware: validation spustí Symfony Validator nad commandem, doctrine_transaction obalí handler databázovou transakcí.

Průvodce používá bus už zde, protože je to idiomatická Symfony cesta: kontroler nezná handler, jen popis záměru. Stejný command lze později zpracovat asynchronně bez zásahu do volajícího kódu. Plný výklad včetně oddělených busů pro commandy a queries přináší kapitola CQRS.

Aplikační služba má tedy v Symfony 8 podobu command nebo query handleru. Načte agregáty přes repozitář, zavolá doménovou metodu a zapíše výsledek; žádná doménová pravidla v ní nežijí:

◢ Vzor

Příklad: Implementace command handleru v Symfony 8

php src/UserManagement/Registration/Command/RegisterUser.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Registration\Command;6 7use Symfony\Component\Validator\Constraints as Assert;8 9final readonly class RegisterUser10{11    public function __construct(12        // Trim je tu schválně: UserName si vstup ořízne, takže bez něj13        // by „  a  “ prošlo délkovou kontrolou a spadlo až v hodnotovém14        // objektu jako 500. HTML formulář to maskuje, protože TextType15        // trimuje sám – JSON endpoint ne.16        #[Assert\NotBlank(normalizer: 'trim')]17        #[Assert\Length(min: 2, max: 100, normalizer: 'trim')]18        public string $name,19 20        #[Assert\NotBlank]21        #[Assert\Email(mode: Assert\Email::VALIDATION_MODE_STRICT)]22        public string $email,23 24        #[Assert\NotBlank]25        #[Assert\Length(min: 12)]26        public string $password,27    ) {}28}

php src/UserManagement/Registration/Command/RegisterUserHandler.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Registration\Command;6 7use App\UserManagement\Domain\Exception\DuplicateEmailException;8use App\UserManagement\Domain\Model\User;9use App\UserManagement\Domain\Repository\UserRepository;10use App\UserManagement\Domain\ValueObject\Email;11use App\UserManagement\Domain\ValueObject\HashedPassword;12use App\UserManagement\Domain\ValueObject\UserId;13use App\UserManagement\Domain\ValueObject\UserName;14use Doctrine\DBAL\Exception\UniqueConstraintViolationException;15use Doctrine\ORM\EntityManagerInterface;16use Symfony\Component\DependencyInjection\Attribute\Target;17use Symfony\Component\Messenger\Attribute\AsMessageHandler;18use Symfony\Component\Messenger\MessageBusInterface;19 20#[AsMessageHandler(bus: 'command.bus')]21final readonly class RegisterUserHandler22{23    public function __construct(24        private UserRepository $userRepository,25        private EntityManagerInterface $em,26        #[Target('event.bus')]27        private MessageBusInterface $eventBus,28    ) {}29 30    public function __invoke(RegisterUser $command): void31    {32        $email = Email::fromUserInput($command->email);33 34        $user = User::register(35            UserId::generate(),36            new UserName($command->name),37            $email,38            HashedPassword::fromPlainText($command->password),39        );40 41        try {42            $this->userRepository->save($user);43            // Explicitní flush kvůli unique constraintu: middleware44            // doctrine_transaction flushuje až po návratu handleru a porušení45            // constraintu by vybublalo mimo tento try/catch. Commit dál46            // řídí middleware.47            $this->em->flush();48        } catch (UniqueConstraintViolationException $e) {49            // Spoléháme na DB unique constraint na sloupci `email`. Aplikační check50            // přes findByEmail() je vůči souběžným registracím nedostatečný (TOCTOU51            // race – dvě paralelní volání obě projdou check a obě uloží).52            throw DuplicateEmailException::with($email, $e);53        }54 55        // Bez tohoto kroku zůstane UserRegistered ležet v agregátu a nikdo56        // se o registraci nedozví – ani posluchač, který zakládá přihlašovací57        // záznam. Uživatel se pak nemůže přihlásit a nic přitom nespadne.58        foreach ($user->releaseEvents() as $event) {59            $this->eventBus->dispatch($event);60        }61    }62}

! Pozor

Race condition v naivní variantě s `findByEmail()`

Naivní handler zjišťuje unikátnost přes findByEmail() před save(). To je TOCTOU race: dvě paralelní registrace se stejným e-mailem obě projdou kontrolou (databáze ještě neviděla zápis té druhé) a obě se úspěšně uloží. Vzniknou dva uživatelé se stejným e-mailem.

Bezpečné řešení má dvě vrstvy:

DB unique constraint na sloupci email. Druhý INSERT vyhodí UniqueConstraintViolationException. Jako jediná vrstva garantuje unikátnost i při souběžných requestech.
Překlad na doménovou výjimku v command handleru, aby kontroler infrastrukturní typy znát nemusel. Repozitář to v této podobě nezvládne, protože jeho save() jen volá persist(). Handler proto vědomě importuje EntityManagerInterface i výjimku z DBAL. Je to pragmatický ústupek od Dependency Rule, který si vynutil explicitní flush.

Explicitní flush() v handleru má konkrétní důvod: databázový constraint se vyhodnotí až při flushi (viz dvojí transakce). Má-li se infrastrukturní výjimka přeložit na doménovou ještě v handleru, musí flush proběhnout uvnitř jeho try bloku. Middleware pak při commitu už jen potvrdí zapsané SQL.

Aplikační check přes findByEmail() můžete ponechat navíc pro hezčí chybovou hlášku v běžném (ne-souběžném) případu, ale nikdy jako jedinou ochranu.

◢ Vzor

Příklad: doménová výjimka s factory metodou

php src/UserManagement/Domain/Exception/DuplicateEmailException.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Domain\Exception;6 7use App\UserManagement\Domain\ValueObject\Email;8 9final class DuplicateEmailException extends \DomainException10{11    public static function with(Email $email, ?\Throwable $previous = null): self12    {13        return new self(14            sprintf('User with e-mail "%s" already exists.', $email->value),15            previous: $previous,16        );17    }18}

◢ Vzor

Příklad: Implementace query handleru v Symfony 8

php src/UserManagement/Profile/Query/GetUserProfile.php + UserProfile.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Profile\Query;6 7final readonly class GetUserProfile8{9    public function __construct(10        public string $userId,11    ) {}12}13 14// Vlastní soubor – PSR-4 by druhou třídu v GetUserProfile.php nenašel.15// Odpověď dotazu: hodnotové objekty ani agregát ven nepouštíme,16// šablona ani API by s nimi neuměly nic užitečného udělat.17final readonly class UserProfile18{19    public function __construct(20        public string $id,21        public string $name,22        public string $email,23        public \DateTimeImmutable $createdAt,24    ) {}25}

php src/UserManagement/Profile/Query/GetUserProfileHandler.php (verze nad agregátem)

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Profile\Query;6 7use App\UserManagement\Domain\Repository\UserRepository;8use App\UserManagement\Domain\ValueObject\UserId;9use Symfony\Component\Messenger\Attribute\AsMessageHandler;10 11#[AsMessageHandler(bus: 'query.bus')]12final readonly class GetUserProfileHandler13{14    public function __construct(15        private UserRepository $userRepository,16    ) {}17 18    public function __invoke(GetUserProfile $query): ?UserProfile19    {20        $user = $this->userRepository->findById(new UserId($query->userId));21 22        if ($user === null) {23            return null;24        }25 26        return new UserProfile(27            id: $user->id->value,28            name: $user->name()->value,29            email: $user->email()->value,30            createdAt: $user->createdAt,31        );32    }33}

RegisterUserHandler a GetUserProfileHandler jsou aplikační služby (command a query handlery). Koordinují use case a delegují doménovou logiku na entitu nebo doménovou službu.

Čtení zde vede přes repozitář agregátu, tedy přes write model. Pro čtyři pole to stačí a zbytečnou vrstvu to nepřidává. Jakmile profil začne zobrazovat počet objednávek nebo úroveň členství, přestane to vycházet: data leží v jiných kontextech a agregát je nemá odkud vzít. Tou hranicí se zabývá kapitola o CQRS, kde GetUserProfileHandler čte z vlastního read repozitáře a vrací bohatší UserProfileViewModel.

§ Poznámka

Kde validovat: Symfony Validator vs. doménová validace

V DDD existují dva druhy validace, každý na jiné vrstvě:

Symfony Validator (aplikační vrstva) – validace vstupních dat na úrovni Commands a Queries: formát e-mailu, délka jména, povinná pole. Atributy #[Assert\Email], #[Assert\NotBlank] patří přímo na command třídy. Tato validace chrání doménovou vrstvu před neplatnými vstupy.
Doménová validace (doménová vrstva) – doménová pravidla, která vynucují entity, agregáty a value objects: „uživatel s tímto e-mailem již existuje“, „objednávku nelze potvrdit bez položek“. Je součástí doménového modelu a na Symfony Validatoru nesmí záviset.

Pravidlo: formát vynucuje hodnotový objekt vždy, je to jeho invariant. Symfony Validator tutéž kontrolu opakuje na hraně aplikace, aby neplatný vstup skončil srozumitelnou chybovou zprávou, ne doménovou výjimkou. Pořadí obou kontrol má viditelný důsledek: validátor běží nad surovým řetězcem z requestu, tedy před Email::fromUserInput(). Adresa s mezerami na krajích proto skončí na 422, ne na 409; normalizace se k ní nedostane. Sémantická pravidla („uživatel s tímto e-mailem již existuje“) patří výhradně doménové vrstvě.

Dvojí kontrola formátu není redundance zadarmo: obě strany musí být zajedno. Assert\Email má výchozí režim html5, který je volnější než strict; režim strict vyžaduje balíček egulias/email-validator. Command s html5 a VO s FILTER_VALIDATE_EMAIL proto propustí jinou množinu adres a rozdíl se projeví až doménovou výjimkou místo validační hlášky. Command RegisterUser výše volí strict právě proto.

Kolik validace patří na hranu aplikace, je zároveň otevřený spor. Zastánci always-valid modelu argumentují, že agregát nesmí existovat v neplatném stavu a validace na hraně je jen lepší UX. Druhý tábor připouští dočasně neplatný model a validaci soustřeďuje do jednoho kroku před uložením. Průvodce drží první variantu.

10.14 Implementace kontrolerů#

Kontroler je adaptér mezi HTTP a aplikační vrstvou. Smí: validovat formát vstupu, transformovat ho na command/query, dispatchovat, přeložit doménovou výjimku na HTTP odpověď. Nesmí: nést doménová pravidla, volat repozitáře přímo, manipulovat s agregáty.

Symfony k tomu nabízí #[MapRequestPayload]: deserializuje a validuje JSON požadavek přímo do typového commandu. Pro klasické HTML formuláře existuje varianta #[MapRequestPayload(acceptFormat: 'form')] nebo Symfony Form.

◢ Vzor

Příklad: kontroler s MapRequestPayload (JSON API)

Kontroler je JSON protějšek HTML formuláře z kapitoly o CQRS. Oba posílají tentýž command, liší se jen tím, jak čtou vstup a co vracejí. Proto mají různá jména a mohou v projektu existovat vedle sebe.

php src/UserManagement/Registration/Controller/RegistrationApiController.php

1<?php2 3declare(strict_types=1);4 5namespace App\UserManagement\Registration\Controller;6 7use App\UserManagement\Domain\Exception\DuplicateEmailException;8use App\UserManagement\Registration\Command\RegisterUser;9use Symfony\Component\HttpFoundation\JsonResponse;10use Symfony\Component\HttpFoundation\Response;11use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;12use Symfony\Component\Messenger\Exception\HandlerFailedException;13use Symfony\Component\Messenger\MessageBusInterface;14use Symfony\Component\Routing\Attribute\Route;15 16final class RegistrationApiController17{18    public function __construct(19        private readonly MessageBusInterface $commandBus,20    ) {}21 22    #[Route('/api/register', name: 'api_register', methods: ['POST'])]23    public function register(24        #[MapRequestPayload] RegisterUser $command,25    ): Response {26        try {27            $this->commandBus->dispatch($command);28        } catch (HandlerFailedException $e) {29            foreach ($e->getWrappedExceptions() as $wrapped) {30                if ($wrapped instanceof DuplicateEmailException) {31                    return new JsonResponse(32                        ['error' => $wrapped->getMessage()],33                        Response::HTTP_CONFLICT,34                    );35                }36            }37 38            throw $e;39        }40 41        return new JsonResponse(['status' => 'created'], Response::HTTP_CREATED);42    }43}

MapRequestPayload převezme deserializaci, validaci přes Symfony Validator (atributy #[Assert\…] na commandu) i překlad chyby validace na HTTP 422. Kontroler tak má jen tři odpovědnosti: dispatch, mapování doménových výjimek na HTTP, návrat odpovědi.

! Pozor

Messenger balí výjimky

Častá past: catch (DuplicateEmailException) kolem dispatch() nikdy nechytí nic. Synchronní Messenger každou výjimku z handleru zabalí do HandlerFailedException, takže se původní typ na catch blok nepropaguje. Zabalené výjimky zpřístupňuje getWrappedExceptions(); je jich pole, protože jedna zpráva může mít víc handlerů. Kontroler proto chytá obálku, projde zabalené výjimky a na známé doménové typy reaguje HTTP odpovědí. Vše ostatní pošle dál. Ticho po neznámé chybě by maskovalo skutečné selhání. Kdo nechce iteraci opakovat v každém kontroleru, napíše dekorátor command busu, který první zabalenou výjimku rozbalí a vyhodí znovu. Ani HandleTrait výjimky nerozbaluje. Vrací sice návratovou hodnotu handleru (z HandledStamp), ale HandlerFailedException propouští zabalenou stejně jako přímý dispatch.

§ Poznámka

Symfony Form patří nad command, ne nad entitu

Adresáře Form/ ve struktuře projektu drží FormType pro HTML formuláře. Rozhoduje hodnota data_class: formulář se váže na command (DTO), nikdy na doménovou entitu. Form komponenta totiž nastavuje vlastnosti napřímo a obchází factory metody i invarianty agregátu. Rozepsaný formulář by držel User v nekonzistentním stavu. Tok je stejný jako u JSON API: Form naplní RegisterUser, kontroler ho dispatchne, handler teprve vytvoří agregát. U readonly commandu s povinnými parametry konstruktoru data_class nefunguje. Bez předaných dat se Form pokusí zavolat new RegisterUser() bez argumentů a skončí na ArgumentCountError. S předvyplněnou instancí zase PropertyAccess do promovaných readonly vlastností nezapíše a vyhodí NoSuchPropertyException. Formulář proto vrací pole a command z něj skládá kontroler.

Má to jeden důsledek, který se často přehlédne: bez data_class formulář constrainty commandu nepřebírá. Validace běží až na sběrnici, tedy po sestavení commandu. Prázdné pole, které TextType mapuje na null, tak shodí konstruktor dřív, než se k validaci dojde. V prohlížeči to zamaskuje HTML5 required, ale klient bez klientské validace dostane 500. Formulář proto potřebuje vlastní NotBlank na každém poli, i když totéž pravidlo nese command.

§ Poznámka

Symfony idiomy: `#[AsAlias]` pro repozitáře

Místo aliasování v services.yaml můžete použít atribut #[AsAlias] přímo na implementaci:

php src/UserManagement/Infrastructure/Repository/DoctrineUserRepository.php (s AsAlias)

1<?php2 3use App\UserManagement\Domain\Repository\UserRepository;4use Symfony\Component\DependencyInjection\Attribute\AsAlias;5 6#[AsAlias(id: UserRepository::class)]7final class DoctrineUserRepository implements UserRepository8{9    // ...10}

DI Container automaticky zaregistruje rozhraní UserRepository jako alias na DoctrineUserRepository. services.yaml zůstane čistý a vazba leží v jednom souboru s implementací. Pro většinu projektů je to preferovaná cesta.

Kontroler je tenký, takže těžiště testů leží pod ním. Agregáty se testují jako čisté PHP bez kernelu. Aplikační handlery pokrývá unit test s in-memory fake repozitářem. Unique constraint, jeho překlad na doménovou výjimku a transakční chování fake neověří; ty patří do integračního testu proti testovací databázi. Konkrétní testy po vrstvách rozebírá kapitola Testování DDD.

Mimo kontroler zůstává i autorizace; má vlastní kapitolu Autorizace v DDD. Stručně: otázku „smí tento uživatel vykonat tento use case na tomto objektu“ řeší use-case vrstva přes Symfony Voter, zatímco doménové invarianty zůstávají v agregátu. Kapitola zavádí čtyřvrstvý rámec od HTTP firewallu po pravidla na úrovni polí a ukazuje, proč doménová pravidla do Voteru nepatří.

10.15 Dependency Injection a autowiring#

DI Container v Symfony 8 váže rozhraní z doménové vrstvy na konkrétní implementaci v infrastruktuře. Konfigurace určuje, kterou třídu autowiring injektuje, když handler typuje na UserRepository:

◢ Vzor

Příklad: Konfigurace služeb v Symfony 8

yaml config/services.yaml (výřez: doménové služby)

1# config/services.yaml2services:3    _defaults:4        autowire: true5        autoconfigure: true6 7    # Registrace všech služeb v adresáři src/8    App\:9        resource: '../src/'10        exclude:11            - '../src/Kernel.php'12            - '../src/*/Domain/Model/'13            - '../src/*/Domain/ValueObject/'14            - '../src/*/Domain/Event/'15 16    # Alias rozhraní → implementace. Klíč je FQN rozhraní, hodnota je @-reference17    # na existující službu (DoctrineUserRepository zaregistruje už blok App\:18    # výše). Vznikne tak jediná instance, na kterou se odkazují obě jména.19    App\UserManagement\Domain\Repository\UserRepository: '@App\UserManagement\Infrastructure\Repository\DoctrineUserRepository'20    App\Ordering\Domain\Repository\OrderRepository: '@App\Ordering\Infrastructure\Repository\DoctrineOrderRepository'21 22    # Messenger busy se konfigurují v config/packages/messenger.yaml, nikoli zde.23    # Při dvou a více busech je default_bus povinný, jinak FrameworkBundle24    # kompilaci kontejneru odmítne:25    # framework:26    #     messenger:27    #         default_bus: command.bus28    #         buses:29    #             command.bus:30    #                 middleware:31    #                     - validation32    #                     - doctrine_transaction33    #             query.bus:34    #                 middleware:35    #                     - validation

! Pozor

Pozor: alias `@...` vs. nová služba `class: ...`

Dva podobné zápisy v services.yaml se chovají různě:

App\…\UserRepository: '@App\…\DoctrineUserRepository' – alias. Kontejner použije existující službu pod druhým jménem. Jedna instance, dvě jména.
App\…\UserRepository: { class: App\…\DoctrineUserRepository } – nová služba pod klíčem rozhraní. Vznikne druhá instance DoctrineUserRepository. Obě dostanou týž EntityManager, ale stav, který si repozitář drží, existuje dvakrát, a dekorátor nebo tag nastavený na jednu instanci se druhé netýká. Při autowiringu pak není na první pohled jasné, kterou instanci kontejner do závislých služeb injektuje.

Idiomatičtější forma je atribut #[AsAlias] přímo na implementaci, viz Symfony idiomy: #[AsAlias]. Konfigurace v YAML se hodí, když implementace patří do jiného balíčku, který nemůžete upravit.

Alias zajistí, že Symfony DI Container injektuje stejnou instanci DoctrineUserRepository všude, kde závislost typuje na UserRepository. Doménové modely, hodnotové objekty a události se z auto-registrace vylučují; nejsou to služby, ale data. Kdo nechce udržovat glob vzory v services.yaml, označí takovou třídu atributem #[Exclude] ze Symfony\Component\DependencyInjection\Attribute; kontejner ji pak přeskočí bez ohledu na resource:.

Autowiring s oddělenými Bounded Contexts

Ve větších projektech s více Bounded Contexts se autowiring konfiguruje pro každý kontext samostatně. Každý kontext dostane vlastní blok v services.yaml, takže se hranice promítne i do service containeru. Následující konfigurace nahrazuje blok App\: z předchozí ukázky, nedoplňuje ho. Rozdíl je citelný: souhrnný App\: zaregistruje i to, na co se zapomnělo, per-kontextový výčet nic takového nemá. Třída v adresáři, který ve výčtu chybí, prostě není službou. Pokud na ní nic nezávisí (handler, kontroler), chybu neohlásí lint:container, ale až běh.

◢ Vzor

Příklad: Samostatný autowiring pro každý Bounded Context

yaml config/services.yaml (kanonická konfigurace knihy)

1# config/services.yaml2services:3    _defaults:4        autowire: true5        autoconfigure: true6 7    # ──────────────────────────────────────────────────8    # Bounded Context: UserManagement9    # ──────────────────────────────────────────────────10    App\UserManagement\:11        resource: '../src/UserManagement/'12        exclude:13            - '../src/UserManagement/Domain/Model/'14            - '../src/UserManagement/Domain/ValueObject/'15            - '../src/UserManagement/Domain/Event/'16 17    App\UserManagement\Domain\Repository\UserRepository: '@App\UserManagement\Infrastructure\Repository\DoctrineUserRepository'18 19    # ──────────────────────────────────────────────────20    # Bounded Context: Ordering21    # ──────────────────────────────────────────────────22    App\Ordering\:23        resource: '../src/Ordering/'24        exclude:25            - '../src/Ordering/Domain/Model/'26            - '../src/Ordering/Domain/ValueObject/'27            - '../src/Ordering/Domain/Event/'28 29    App\Ordering\Domain\Repository\OrderRepository: '@App\Ordering\Infrastructure\Repository\DoctrineOrderRepository'30 31    # ──────────────────────────────────────────────────32    # SharedKernel: sdílené komponenty napříč kontexty33    # ──────────────────────────────────────────────────34    App\SharedKernel\:35        resource: '../src/SharedKernel/'36        exclude:37            # Celé Domain/, ne jen Domain/ValueObject/: Money a Currency38            # leží přímo v Domain/ a jinak se zaregistrují jako služby.39            - '../src/SharedKernel/Domain/'40 41    # ──────────────────────────────────────────────────42    # Kontexty z kapitol o Outboxu a ságách43    #44    # POZOR: tyto adresáře vzniknou až v kapitolách 11, 14 a 15. Kdo čte45    # popořadě, přidá si každý řádek s jeho kapitolou – jinak kompilace46    # kontejneru spadne na „The file ../src/Reporting/ does not exist“.47    # ──────────────────────────────────────────────────48    App\Identity\: { resource: '../src/Identity/', exclude: ['../src/Identity/Domain/'] }49    App\Outbox\:    { resource: '../src/Outbox/' }50    App\Inbox\:     { resource: '../src/Inbox/' }51    App\Reporting\: { resource: '../src/Reporting/' }52    # Sběrnicové middleware z 12.15 sedí mimo kontexty. Řádek přidejte53    # až s ním – neexistující adresář shodí kompilaci kontejneru hláškou54    # „The file ../src/Infrastructure/ does not exist“.55    App\Infrastructure\: { resource: '../src/Infrastructure/' }56    App\Payment\:   { resource: '../src/Payment/',   exclude: ['../src/Payment/Domain/Event/'] }57    App\Warehouse\: { resource: '../src/Warehouse/', exclude: ['../src/Warehouse/Domain/Event/'] }58    App\Shipping\:  { resource: '../src/Shipping/',  exclude: ['../src/Shipping/Domain/ValueObject/'] }59 60    App\Outbox\Application\OutboxRepository: '@App\Outbox\Infrastructure\DoctrineOutboxRepository'61    App\Inbox\Application\InboxRepository: '@App\Inbox\Infrastructure\DbalInboxRepository'62    App\Ordering\Application\Saga\OrderSagaRepository: '@App\Ordering\Infrastructure\Saga\DoctrineOrderSagaRepository'63    App\Payment\Domain\PaymentGateway: '@App\Payment\Infrastructure\InMemoryPaymentGateway'64    App\Warehouse\Domain\StockService: '@App\Warehouse\Infrastructure\InMemoryStockService'65    App\Shipping\Domain\ShippingService: '@App\Shipping\Infrastructure\InMemoryShippingService'66    App\Reporting\Application\ReadModelStore: '@App\Reporting\Infrastructure\DbalReadModelStore'67    App\UserManagement\Profile\ReadModel\UserProfileReadRepository: '@App\UserManagement\Infrastructure\ReadModel\DbalUserProfileReadRepository'

Posledních osm řádků tvoří aliasy rozhraní na implementaci. Většinu z nich by autowiring vytvořil sám, protože rozhraní i jeho jediná implementace leží ve stejném bloku resource (viz kapitola o architektonických stylech). Explicitní řádek ale dokumentuje volbu výchozího adaptéru a vydrží i ve chvíli, kdy vedle InMemoryPaymentGateway přibude skutečná platební brána a automatický alias zanikne.

10.16 Další četba a citace#

Symfony – The Symfony Framework Best Practices. Doporučení atributového mapování Doctrine a dovětek, který připouští odchylku od výchozí adresářové struktury.
PHP Manual – Lazy Objects (PHP 8.4). Nativní lazy ghost a lazy proxy bez generované podtřídy.
Doctrine ORM – Basic Mapping. Podpora property hooks od ORM 3.4 a chování DQL nad hodnotou uloženou ve sloupci.
Martin Fowler – Data Mapper, Patterns of Enterprise Application Architecture (2002). Rodičovský vzor odděleného persistence modelu.
Vladimir Khorikov – Having the domain model separate from the persistence model (2016). Argumentace proti plnohodnotnému persistence modelu.
Matthias Noback – DDD entities and ORM entities (2022). „80% decoupling“ jako alternativa k oddělenému modelu; navazuje na DDD and your database (2020).
Symfony – Object Mapper. Deklarativní mapování objektu na objekt přes atribut #[Map].
Doctrine ORM – UPGRADE.md. Odstranění annotation a YAML driveru v ORM 3 a stav nativních lazy objektů.
Symfony – Messenger. Routing zpráv, atribut #[AsMessage] a přednost konfigurace framework.messenger.routing.
Doctrine ORM – Events. Omezení onFlush a postFlush, kvůli kterým se lifecycle listener nehodí na publikaci doménových událostí.
Matthias Noback – Does it belong in the application or domain layer? (2021). Heuristika pro dělbu mezi aplikační a doménovou vrstvou.
Vladimir Khorikov – Domain events: simple and reliable solution (2017). Sběr událostí v agregátu a publikace až po commitu.
V tomto průvodci navazují kapitoly Návrh agregátu, CQRS, Outbox Pattern a Testování DDD.

Časté otázky

Kam v Symfony projektu patří doménová vrstva a proč ji držet odděleně?

Doménová vrstva patří do samostatného adresáře, odděleně od kontrolerů, Doctrine mapování a infrastruktury. V tomto průvodci je to src/<BoundedContext>/Domain/, například src/UserManagement/Domain/. Izolace umožňuje testovat a refaktorovat model bez závislosti na Symfony životním cyklu a dovoluje přenést doménu i do jiného technologického stacku. Viz sekci Struktura projektu.

Jak mapovat agregát v Doctrine bez toho, aby doména závisela na ORM?

V tomto průvodci používáme Doctrine atributy přímo na agregátu jako pragmatickou výchozí volbu: jsou to metadata, ne chování. Doménu bez jediné stopy ORM zajistí oddělený persistence model, v tomto průvodci nazývaný Persisted Object Pattern. Doménová třída zůstane POPO, vedle ní v infrastruktuře stojí samostatná persistence třída s atributy a mapper mezi nimi. Rodičovským vzorem je Fowlerův Data Mapper. Khorikov i Noback tuto separaci označují za drahou a ve většině projektů zbytečnou, takže jde o menšinovou volbu, ne o výchozí doporučení. Detail v sekci Persisted Object Pattern.

Jak odlišit Aplikační službu od Doménové služby?

Doménová služba drží čistou doménovou logiku, která přirozeně nepatří žádnému agregátu ani hodnotovému objektu; je bezstavová a nekomunikuje s infrastrukturou. Aplikační služba naopak orchestruje use case: přijme vstup z kontroleru, načte agregáty přes repozitář, zavolá doménovou logiku a předá výsledek k persistenci. Aplikační služba nikdy neobsahuje doménová pravidla, pouze posloupnost kroků. Podrobný rozbor v sekci Aplikační služby a Doménové služby.

Mají doménové operace vyhazovat výjimky, nebo vracet Result typ?

V PHP a Symfony ekosystému jsou výjimky dominantní cestou. Při porušení invariantu agregát vyhodí konkrétní doménovou výjimku (například InsufficientFundsException). Aplikační vrstva ji přeloží na HTTP odpověď nebo zprávu uživateli. Result/Either typ je v PHP možný, ale přidává složitost bez odpovídajícího přínosu. Kontrolery zachytávají jen doménové podtypy, nikdy obecnou Exception. Rozbor variant v sekci Strategie zpracování chyb.

Kdy použít Doctrine Custom Type pro Value Object?

Doctrine Custom Type se hodí tam, kde se hodnotový objekt ukládá jako jednoduchá hodnota v jednom sloupci: peněžní částka, e-mail, URL, vlastní identifikátor. Custom Type přeloží hodnotový objekt při zápisu do primitivu a při čtení ho zpět rekonstruuje. Doménový kód pak pracuje vždy s typovým objektem. Pro hodnotové objekty složené z více sloupců je vhodnější embeddable mapování. Detailní rozbor v sekci Doctrine custom types pro Value Objects.