Kapitola 10 · Architektura · Implementace DDD v Symfony 8

Implementace DDD v Symfony 8

Praktický překlad DDD konceptů do Symfony 8: jak strukturovat projekt podle Bounded Contextů, jak persistovat agregáty přes Doctrine, jak konfigurovat Messenger a kdy sáhnout po Doctrine custom types pro hodnotové objekty.

Autor M. Katuščák

Doba čtení ≈ 35 min

Náročnost pokročilá

Publikováno · Aktualizováno 24. 4. 2025 · 8. 7. 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. V praxi jde 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#

Následující 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, přenositelné mezi projekty. Symfony vrstva implementuje kontrakty definované doménou (repository interface, event dispatch) a zajišťuje HTTP, persistenci a messaging.

Směr závislostí je určující: Symfony závisí na DDD (implementuje jeho rozhraní), nikdy naopak. Doménová vrstva neimportuje žádný Symfony namespace. Díky tomu lze Doctrine nahradit jiným ORM nebo Messenger jiným bus systémem, aniž by se dotklo doménové logiky. 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.php22│   │   ├── Form/               # Forms23│   │   │   └── RegistrationFormType.php24│   │   └── View/               # Views25│   │       └── registration.html.twig26│   └── Profile/                # Feature: Profil uživatele27│       ├── Query/              # Queries28│       │   ├── GetUserProfile.php29│       │   └── GetUserProfileHandler.php30│       ├── Controller/         # Controllers31│       │   └── ProfileController.php32│       ├── Form/               # Forms33│       │   └── ProfileFormType.php34│       └── View/               # Views35│           └── profile.html.twig36├── OrderManagement/           # Bounded Context: Správa objednávek37│   ├── Domain/                # Doménová vrstva pro OrderManagement38│   │   ├── Model/             # Doménové modely39│   │   │   ├── Order.php40│   │   │   └── OrderItem.php41│   │   ├── ValueObject/       # Hodnotové objekty42│   │   │   ├── OrderId.php43│   │   │   └── Money.php44│   │   ├── Event/             # Doménové události45│   │   │   └── OrderCreated.php46│   │   └── Repository/        # Repozitáře (rozhraní)47│   │       └── OrderRepository.php48│   ├── Infrastructure/        # Infrastruktura pro OrderManagement49│   │   └── Repository/        # Implementace repozitářů50│   │       └── DoctrineOrderRepository.php51│   ├── Checkout/              # Feature: Pokladna52│   │   ├── Command/           # Commands53│   │   │   ├── CreateOrder.php54│   │   │   └── CreateOrderHandler.php55│   │   ├── Controller/        # Controllers56│   │   │   └── CheckoutController.php57│   │   ├── Form/              # Forms58│   │   │   └── CheckoutFormType.php59│   │   └── View/              # Views60│   │       └── checkout.html.twig61│   └── OrderHistory/          # Feature: Historie objednávek62│       ├── Query/             # Queries63│       │   ├── GetOrderHistory.php64│       │   └── GetOrderHistoryHandler.php65│       ├── Controller/        # Controllers66│       │   └── OrderHistoryController.php67│       └── View/              # Views68│           └── order_history.html.twig69└── SharedKernel/              # Skutečně sdílené komponenty70    ├── Domain/                # Sdílená doménová logika71    │   └── ValueObject/       # Sdílené hodnotové objekty72    │       └── Id.php         # Abstraktní ID73    └── Infrastructure/        # Sdílená infrastruktura74        └── Persistence/       # Sdílené komponenty pro persistenci75            └── Doctrine/76                └── Mapping/77                    └── MappingTrait.php

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.

10.03 Implementace entit#

Vstupní bod do agregátu je 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()). To zaručuje, že nelze vytvořit agregát v nekonzistentním stavu. Definice entity je v kapitole Základní koncepty; tato sekce řeší 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    public function rename(UserName $newName): void75    {76        if ($this->name->equals($newName)) {77            return;78        }79 80        $this->name = $newName;81    }82 83    public function changeEmail(Email $newEmail): void84    {85        if ($this->email->equals($newEmail)) {86            return;87        }88 89        $this->email = $newEmail;90    }91}

Detaily implementace:

final class User extends AggregateRoot. Bázová třída poskytuje record() a releaseEvents() – sdílené chování pro všechny agregáty, ne duplicitní kopii 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á legální cesta vytvoření. 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 – konstruktorem prochází i rekonstituce uloženého agregátu a ta žádnou událost vyvolat nesmí.
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:

◢ 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('Neplatný formát e-mailu: "%s".', $value),15            );16        }17    }18 19    public static function fromUserInput(string $raw): self20    {21        // Vstupy z formulářů normalizujeme zde (lowercase, trim).22        // Konstruktor se nedotýká – chrání invariant „dvě instance se stejnou23        // 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}

! Pozor

Limity `FILTER_VALIDATE_EMAIL`

PHP FILTER_VALIDATE_EMAIL ověřuje syntaxi podle zjednodušeného RFC 5322. 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.

V doménové vrstvě tedy validujeme syntakticky. 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, kterou používá i Symfony Validator pod kapotou.

◢ 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 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 readonly 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                'Jméno musí mít %d–%d znaků (zadáno %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á jako sloupec ve stejné tabulce jako vlastník (žádná samostatná tabulka pro VO).

Třetí typ hodnotového objektu je identita agregátu. Generuje se v aplikaci, ne v databázi – handler tak 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('Neplatné UserId: "%s".', $value),17            );18        }19    }20 21    public static function generate(): self22    {23        return new self((string) Uuid::v7());24    }25 26    public function equals(self $other): bool27    {28        return $this->value === $other->value;29    }30}

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ší: zakazuje 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. V doménovém modelu je to past. Hook se spustí při každém zápisu včetně hydratace z databáze, kdežto konstruktor Doctrine obchází. Validace by se tedy spouštěla právě tam, kde je zbytečná, a mlčela tam, kde na ní záleží.

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í. Publikaci doménových23        // událostí (releaseEvents()) zajišťuje aplikační vrstva až po commitu;24        // spolehlivý mechanismus je Outbox Pattern (viz callouty níže).25        $this->em->persist($user);26    }27 28    public function findById(UserId $id): ?User29    {30        return $this->em->find(User::class, $id->value);31    }32 33    public function findByEmail(Email $email): ?User34    {35        return $this->em->getRepository(User::class)36            ->findOneBy(['email' => $email->value]);37    }38}

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. Publikace doménových událostí je samostatný krok aplikační vrstvy – proběhne až po commitu, aby příjemci viděli uložený stav.

! 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á vlastnit jedna vrstva – doporučená volba 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 – a pokud se transakce poté vrátí zpět (rollback), listenery už reagovaly na událost, která se nikdy nestala. Spolehlivé řešení je opět Outbox Pattern: událost se commituje spolu s agregátem.

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 dva jednosměrné mappery překládají mezi nimi. 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 a ztrácí se 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 hranic agregátu nezávisle na schématu databáze – a dodává, že většina projektů, které se toho dovolávají, to nepotřebuje.

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        // bez vyhazování doménových událostí.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 pure varianty

Persisted Object Pattern drží doménu úplně mimo ORM. Žádný atribut, žádný use Doctrine\…, žádná stopa po infrastruktuře. 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 – musí to dělat 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 mapperech. Žádný compiler 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 – to stačí pro insert. 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.

Doporučení: použít Persisted Object jen v kontextech, kde je oddělení opravdu důležité (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í.

V dalších příkladech v tomto průvodci pokračujeme s atributy přímo na agregátech. Persisted Object Pattern dále nerozvíjíme – principy jsou identické, jen vyžadují explicitní mapper na každý agregát.

10.07 Doctrine custom types pro Value Objects#

Sekce Implementace entit deklaruje vlastnosti přímo typu Email nebo UserId. Tuto hydrataci zajišťuje Doctrine custom type – konvertor mezi databázovým primitivem a hodnotovým objektem. Zde je jeho implementace a registrace.

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

◢ Vzor

Registrace custom type v Symfony

yaml config/packages/doctrine.yaml

1# config/packages/doctrine.yaml2doctrine:3    dbal:4        types:5            email_vo:6                class: App\UserManagement\Infrastructure\Doctrine\Type\EmailType7            user_id:8                class: 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;

Třída záměrně nemá metodu getName() – DBAL 4 ji odstranil. Jméno typu určuje výhradně klíč v doctrine.dbal.types; konstanta NAME slouží jen jako pojmenovaná reference pro atributy #[ORM\Column]. 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 je navíc jedinou neatributovou variantou [8] a nástroje kolem Doctrine ji 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/OrderManagement/Domain/ValueObject/OrderStatus.php

1<?php2 3declare(strict_types=1);4 5namespace App\OrderManagement\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            self::Shipped => [self::Delivered],28            self::Delivered => [],29            self::Cancelled => [],30        };31    }32 33    public function canTransitionTo(self $target): bool34    {35        return in_array($target, $this->allowedTransitions(), true);36    }37}

◢ Vzor

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

php src/OrderManagement/Domain/Model/Order.php

1<?php2 3declare(strict_types=1);4 5namespace App\OrderManagement\Domain\Model;6 7use App\OrderManagement\Domain\Event\OrderCreated;8use App\OrderManagement\Domain\Event\OrderStatusChanged;9use App\OrderManagement\Domain\ValueObject\OrderId;10use App\OrderManagement\Domain\ValueObject\OrderStatus;11use App\SharedKernel\Domain\AggregateRoot;12 13final class Order extends AggregateRoot14{15    private OrderStatus $status;16    private readonly \DateTimeImmutable $createdAt;17 18    private function __construct(19        public readonly OrderId $id,20    ) {21        $this->status = OrderStatus::Draft;22        $this->createdAt = new \DateTimeImmutable();23    }24 25    public static function place(OrderId $id): self26    {27        $order = new self($id);28        $order->record(new OrderCreated($id));29 30        return $order;31    }32 33    public function status(): OrderStatus34    {35        return $this->status;36    }37 38    public function transitionTo(OrderStatus $newStatus): void39    {40        if (!$this->status->canTransitionTo($newStatus)) {41            throw new \DomainException(sprintf(42                'Nelze přejít ze stavu "%s" do stavu "%s".',43                $this->status->value,44                $newStatus->value45            ));46        }47 48        $oldStatus = $this->status;49        $this->status = $newStatus;50 51        $this->record(new OrderStatusChanged($this->id, $oldStatus, $newStatus));52    }53}

§ 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 komplexní typy, které vyžadují validaci, formátování nebo aritmetiku: Money (částka + měna + zaokrouhlování), Email (validace formátu), Address (více polí), DateRange (interval s logikou překrývání).

Obecné pravidlo: pokud typ má konečný, předem známý počet hodnot a nepotřebuje složitou vnitřní logiku, je enum správná volba. Pokud typ obsahuje libovolné hodnoty, validaci nebo výpočty, je namístě hodnotový objekt.

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 confirmed 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/OrderManagement/Domain/Service/PaymentService.php (ANTI-VZOR)

1<?php2 3// ANTI-VZOR: pravidlo „lze platit jen confirmed 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/OrderManagement/Domain/Model/Order.php

1<?php2 3declare(strict_types=1);4 5namespace App\OrderManagement\Domain\Model;6 7use App\OrderManagement\Domain\Event\PaymentRecorded;8use App\OrderManagement\Domain\Exception\InvalidOrderStateTransitionException;9use App\OrderManagement\Domain\ValueObject\Money;10use App\OrderManagement\Domain\ValueObject\OrderStatus;11use App\OrderManagement\Domain\ValueObject\PaymentId;12use App\OrderManagement\Domain\ValueObject\PaymentMethod;13 14final class Order extends AggregateRoot15{16    // ... id, status, items, factory method `place()` viz dříve ...17 18    public function recordPayment(Money $amount, PaymentMethod $method): Payment19    {20        if ($this->status !== OrderStatus::Confirmed) {21            throw InvalidOrderStateTransitionException::cannotTransition(22                $this->status->value,23                OrderStatus::Paid->value,24            );25        }26 27        if (!$amount->equals($this->totalAmount())) {28            throw new \DomainException('Payment amount does not match order total.');29        }30 31        $this->status = OrderStatus::Paid;32 33        $payment = Payment::record(PaymentId::generate(), $this->id, $amount, $method);34 35        $this->record(new PaymentRecorded($this->id, $payment->id(), $amount));36 37        return $payment;38    }39}

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. Invariant „platit lze jen confirmed objednávku“ tedy vynucuje typový systé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/OrderManagement/Application/Command/RecordPaymentHandler.php

1<?php2 3declare(strict_types=1);4 5namespace App\OrderManagement\Application\Command;6 7use App\OrderManagement\Domain\Repository\OrderRepository;8use App\OrderManagement\Domain\Repository\PaymentRepository;9use App\OrderManagement\Domain\ValueObject\Money;10use App\OrderManagement\Domain\ValueObject\OrderId;11use App\OrderManagement\Domain\ValueObject\PaymentMethod;12use Symfony\Component\Messenger\Attribute\AsMessageHandler;13 14#[AsMessageHandler]15final class RecordPaymentHandler16{17    public function __construct(18        private readonly OrderRepository $orders,19        private readonly PaymentRepository $payments,20    ) {}21 22    public function __invoke(RecordPayment $cmd): void23    {24        $order = $this->orders->get(OrderId::fromString($cmd->orderId));25 26        $payment = $order->recordPayment(27            Money::fromAmount($cmd->amount, $cmd->currency),28            PaymentMethod::from($cmd->method),29        );30 31        $this->orders->save($order);32        $this->payments->save($payment);33    }34}

Handler zapisuje dva agregáty v jedné transakci, což je odchylka od pravidla jeden agregát na transakci. Držíme ji vědomě: přechod Order do stavu Paid a vznik odpovídajícího Payment tvoří jediný invariant a rozpad na dvě transakce by připustil zaplacenou objednávku bez platby. Alternativou je eventual consistency – Order publikuje 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. (Pozor: stejně se ukládá v jedné transakci na jeden agregát – viz agregát = transakční hranice.)
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: pravidlo patří 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 jedinou metodou isSatisfiedBy(). Pravidlo „objednávka je způsobilá k expedici“ pak existuje na jednom místě – stejná 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 double-dispatch napojení 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 publikuje 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. 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, Doctrine outbox), retry strategii a serializaci zprávy. Příjemce může běžet v jiném procesu, jiném serveru. Transport lze určit atributem #[AsMessage(transport: 'async')] 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:

In-context, in-request listenery (read model uvnitř téhož kontextu, audit log, cache invalidace uvnitř téhož commitu) → EventDispatcher. Žádná serializace, listenery vidí stejný EntityManager, stejnou transakci.
Cross-context komunikace (publikace události mimo Bounded Context, kterou zpracuje jiný kontext / služba / projekce) → Messenger. Zpráva dorazí do brokera, jiný kontext si ji odebere. Spolehlivé doručení napříč kontexty zajišťuje v produkci Outbox Pattern.

Anti-vzor: používat Messenger jako náhradu za EventDispatcher uvnitř téhož kontextu, protože „je to flexibilnější“. Cena: každá zpráva projde JSON serializací, ztráta typů, ztráta transakční koheze, nutnost správy transportů. Mechanismus se volí podle hranice, kterou událost překračuje – ne podle hypotetické budoucí potřeby.

! 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; je nutné dovolat 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:

◢ Vzor

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

php src/OrderManagement/Domain/Exception/InvalidOrderStateTransitionException.php

1<?php2 3declare(strict_types=1);4 5namespace App\OrderManagement\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            'Nelze přejít ze stavu "%s" do stavu "%s".',16            $from,17            $to,18        ));19    }20}

! 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í.
Nepropagujte infrastrukturní výjimky do doménové vrstvy – repozitáře by je měly zachytit a přeložit na doménové výjimky.
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#

Tato sekce poprvé skládá dohromady trojici command – handler – bus, proto krátké vysvětlení pojmů. 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í (podrobně v kapitole CQRS).

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        #[Assert\NotBlank]13        #[Assert\Length(min: 2, max: 100)]14        public string $name,15 16        #[Assert\NotBlank]17        #[Assert\Email(mode: Assert\Email::VALIDATION_MODE_STRICT)]18        public string $email,19 20        #[Assert\NotBlank]21        #[Assert\Length(min: 12)]22        public string $password,23    ) {}24}

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\Messenger\Attribute\AsMessageHandler;17 18#[AsMessageHandler]19final readonly class RegisterUserHandler20{21    public function __construct(22        private UserRepository $userRepository,23        private EntityManagerInterface $em,24    ) {}25 26    public function __invoke(RegisterUser $command): void27    {28        $email = Email::fromUserInput($command->email);29 30        $user = User::register(31            UserId::generate(),32            new UserName($command->name),33            $email,34            HashedPassword::fromPlainText($command->password),35        );36 37        try {38            $this->userRepository->save($user);39            // Výjimečně explicitní flush. Middleware doctrine_transaction40            // flushuje až po návratu handleru – porušení unique constraintu41            // by tak vybublalo mimo tento try/catch. Překlad na doménovou42            // výjimku ale musí proběhnout zde, proto flush voláme ručně.43            $this->em->flush();44        } catch (UniqueConstraintViolationException $e) {45            // Spoléháme na DB unique constraint na sloupci `email`. Aplikační check46            // přes findByEmail() je vůči souběžným registracím nedostatečný (TOCTOU47            // race – dvě paralelní volání obě projdou check a obě uloží).48            throw DuplicateEmailException::with($email, $e);49        }50    }51}

! Pozor

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

V dřívějších verzích tohoto průvodce handler zjišťoval unikátnost přes findByEmail() před save(). To je TOCTOU race: dvě paralelní registrace se stejným e-mailem obě projdou checkem (databáze ještě neviděla zápis té druhé) a obě se úspěšně uloží. Výsledek: 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. Toto je jediná garance napříč souběžnými requesty.
Překlad na doménovou výjimku v command handleru (nebo lépe v repozitáři), aby aplikační vrstva nemusela znát infrastrukturní typy.

Explicitní flush() v handleru je záměrná odchylka od pravidla „flush vlastní middleware“ (viz dvojí transakce). Databázový constraint se vyhodnotí až při flushi. 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('Uživatel s e-mailem "%s" již existuje.', $email->value),15            previous: $previous,16        );17    }18}

◢ Vzor

Příklad: Implementace query handleru v Symfony 8

php src/UserManagement/Profile/Query/GetUserProfile.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}

php src/UserManagement/Profile/Query/GetUserProfileHandler.php

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]12final readonly class GetUserProfileHandler13{14    public function __construct(15        private UserRepository $userRepository,16    ) {}17 18    public function __invoke(GetUserProfile $query): ?UserProfileViewModel19    {20        $user = $this->userRepository->findById(new UserId($query->userId));21 22        if ($user === null) {23            return null;24        }25 26        return new UserProfileViewModel(27            id: $user->id->value,28            name: (string) $user->name(),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.

§ 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“. Tato validace je součástí doménového modelu a Symfony Validator na ní 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. 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 adapter 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)

php src/UserManagement/Registration/Controller/RegistrationController.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 RegistrationController17{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 – původní typ se 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 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 DoctrineUserRepository jako alias na rozhraní UserRepository. services.yaml zůstane čistý, závislosti zůstanou 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, které se opírají o repozitář, pokrývá kernel test s testovací databází – jen reálná DB ověří unique constraint a transakční chování, in-memory mock je negarantuje. 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

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 (Symfony si DoctrineUserRepository zaregistruje sama18    # přes autowiring výše). Tím vznikne JEDNA instance, na kterou se odkazují obě jména.19    App\UserManagement\Domain\Repository\UserRepository: '@App\UserManagement\Infrastructure\Repository\DoctrineUserRepository'20    App\OrderManagement\Domain\Repository\OrderRepository: '@App\OrderManagement\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: ...`

Drobný rozdíl v syntaxi services.yaml, dramatický rozdíl v chování:

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 – dva EntityManagery, dvě sady listenerů, dva separátní stavy. Při autowiringu může vznikat zmatek, kterou instanci kontejner injektuje do závislých služeb.

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 z auto-registrace vylučujeme – 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 – hranice se tak promítne i do service containeru.

◢ Vzor

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

yaml config/services.yaml

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: OrderManagement21    # ──────────────────────────────────────────────────22    App\OrderManagement\:23        resource: '../src/OrderManagement/'24        exclude:25            - '../src/OrderManagement/Domain/Model/'26            - '../src/OrderManagement/Domain/ValueObject/'27            - '../src/OrderManagement/Domain/Event/'28 29    App\OrderManagement\Domain\Repository\OrderRepository: '@App\OrderManagement\Infrastructure\Repository\DoctrineOrderRepository'30 31    # ──────────────────────────────────────────────────32    # SharedKernel: sdílené komponenty napříč kontexty33    # ──────────────────────────────────────────────────34    App\SharedKernel\:35        resource: '../src/SharedKernel/'36        exclude:37            - '../src/SharedKernel/Domain/ValueObject/'

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 se umisťuje do samostatného adresáře – v tomto průvodci src/<BoundedContext>/Domain/, například src/UserManagement/Domain/ – odděleně od kontrolerů, Doctrine mapování a infrastruktury. 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 existuje 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.