Domain-Driven Design (Symfony)

Building blocks

Value objects

Immutable, self-validating, compared by value. Replace primitive obsession.

// ✅ GOOD — value object enforces its own invariants
final readonly class Email
{
    public function __construct(public string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException("Invalid email: {$value}");
        }
    }

    public function equals(self $other): bool
    {
        return $this->value === $other->value;
    }
}

final readonly class Money
{
    public function __construct(public int $amountInCents, public Currency $currency) {}

    public function add(self $other): self
    {
        if ($this->currency !== $other->currency) {
            throw new \DomainException('Currency mismatch');
        }
        return new self($this->amountInCents + $other->amountInCents, $this->currency);
    }
}

// ❌ BAD — primitives everywhere, no invariants, validation scattered across services
function createOrder(string $email, int $totalCents): void { /* ... */ }

Map value objects with Doctrine embeddables (#[ORM\Embedded]) or a custom DBAL type, so the table stays flat while the model stays rich.

Aggregates protect invariants

• The aggregate root is the only object outside code may hold a reference to.
• Mutations go through behavior methods on the root, never setters.
• Invariants are checked inside those methods — an aggregate can never be in an invalid state.
• Keep aggregates small; reference other aggregates by ID, not object reference.

// ✅ GOOD — behavior methods guard invariants; children reached only through the root
#[ORM\Entity]
class Order
{
    #[ORM\Id, ORM\Column(type: 'uuid')]
    private Uuid $id;

    #[ORM\Column(enumType: OrderStatus::class)]
    private OrderStatus $status;

    /** @var Collection<int, OrderLine> */
    #[ORM\OneToMany(targetEntity: OrderLine::class, mappedBy: 'order', cascade: ['persist'], orphanRemoval: true)]
    private Collection $lines;

    /** @var DomainEvent[] */
    private array $recordedEvents = [];

    private function __construct(Uuid $id)
    {
        $this->id = $id;
        $this->status = OrderStatus::Pending;
        $this->lines = new ArrayCollection();
    }

    public static function place(): self
    {
        $order = new self(Uuid::v7());
        $order->record(new OrderPlaced($order->id));
        return $order;
    }

    public function addLine(Uuid $productId, int $quantity): void
    {
        if ($this->status !== OrderStatus::Pending) {
            throw new \DomainException('Cannot modify a confirmed order'); // invariant
        }
        $this->lines->add(new OrderLine($this, $productId, $quantity));
    }

    public function confirm(): void
    {
        if ($this->lines->isEmpty()) {
            throw new \DomainException('Cannot confirm an empty order'); // invariant
        }
        $this->status = OrderStatus::Confirmed;
        $this->record(new OrderConfirmed($this->id));
    }

    /** @return DomainEvent[] */
    public function releaseEvents(): array
    {
        $events = $this->recordedEvents;
        $this->recordedEvents = [];
        return $events;
    }

    private function record(DomainEvent $event): void
    {
        $this->recordedEvents[] = $event;
    }
}

// ❌ BAD — anemic entity: public setters let any caller break invariants
class Order
{
    public OrderStatus $status;
    public Collection $lines;
    public function setStatus(OrderStatus $s): void { $this->status = $s; }
}

Domain events

Record events inside the aggregate; dispatch them after the transaction commits so subscribers never see uncommitted state. A Doctrine postFlush listener or Messenger does the dispatch.

// ✅ Dispatch recorded events after flush via a Doctrine event subscriber
#[AsDoctrineListener(event: Events::postFlush)]
final class DispatchDomainEventsListener
{
    public function __construct(private readonly MessageBusInterface $eventBus) {}

    public function postFlush(PostFlushEventArgs $args): void
    {
        $uow = $args->getObjectManager()->getUnitOfWork();
        foreach ($uow->getIdentityMap() as $entities) {
            foreach ($entities as $entity) {
                if ($entity instanceof RecordsEvents) {
                    foreach ($entity->releaseEvents() as $event) {
                        $this->eventBus->dispatch($event);
                    }
                }
            }
        }
    }
}

Ubiquitous language

• Name classes and methods with the business vocabulary: Order::confirm(), not Order::setStatusToConfirmed().
• The same term means the same thing in code, tests, and conversation.
• Bounded contexts get their own namespace (App\Sales\…, App\Billing\…); the same word may differ between them.

Gotchas

• Agent generates anemic entities with public setters — model behavior methods that enforce invariants.
• Agent uses primitive string/int for Email, Money, OrderId — introduce value objects.
• Agent references other aggregates by object (#[ORM\ManyToOne] private Customer $customer) — reference by ID across aggregate boundaries.
• Agent dispatches domain events before flush() — record on the aggregate, dispatch after commit.
• Agent puts cross-aggregate logic on an entity — use a stateless domain service.
• Agent makes huge aggregates loading dozens of children — keep them small; consider a separate read model.
• Agent names methods after database operations (save, update) instead of intent (confirm, cancel).