DEV Community: Mykola Vantukh

DDD with Symfony 7: Clean Architecture and Deptrac boundaries

Mykola Vantukh — Mon, 01 Sep 2025 13:26:05 +0000

Domain-Driven Design (DDD) in PHP projects

In recent years, I have worked on projects with high domain complexity: e-commerce platforms and ERP systems. In such systems, the traditional service-layer approach quickly reaches its limits: business logic grows uncontrollably, dependencies become tangled, and the codebase turns into a chaotic, hard-to-maintain structure.

To address this, we applied Domain-Driven Design combined with layered architecture. This approach made it possible to isolate business rules from technical concerns, maintain clear boundaries between components, and keep the project manageable over the long term.

This architecture is framework-agnostic. It fits both Symfony and Laravel, because the business logic (Domain + Application) does not depend on framework features.

Folder structure

src
├── Catalogue/                     # Catalogue Bounded Context
│   ├── Application/               # Use cases (commands, queries, handlers, ports)
│   ├── Contracts/                 # Published Language (DTOs, ports for other BCs)
│   ├── Domain/                    # Entities, value objects, repos, exceptions
│   ├── Infrastructure/            # Adapters: OHS, Doctrine, Validation
│   └── Presentation/              # API controllers
│
├── Order/                         # Order Bounded Context
│   ├── Application/               # Commands, queries, ports
│   ├── Domain/                    # Pure Order model
│   ├── Infrastructure/            # Doctrine, Validation
│   ├── Integration/               # ACL to Catalogue
│   └── Presentation/              # HTTP/CLI controllers
│
└── SharedKernel/                  # Cross-cutting primitives
    ├── Domain/                    # Value objects, interfaces
    ├── Http/                      # Transport-agnostic HTTP helpers
    └── Infrastructure/            # Error responders, exception mapping

Explore full demo project: on GitHub

Architecture Layers

Each bounded context is split into four core layers.

Domain

Pure business logic: entities, aggregates, value objects, invariants.
Independent of Symfony, Doctrine, or any technical framework.

class Order {
      public static function create(string $id, Money $amountToPay, OrderLine ...$lines): self
    {
        $amountToPayValue = $amountToPay->toMinor();
        if ($amountToPayValue <= 0) {
            throw new NonPositiveOrderAmountException("Order amount must be greater than zero.");
        }

        $order = new self();
        $order->id = $id;
        $order->amountToPay = $amountToPayValue;
        $order->status = OrderStatus::PENDING->value;
        $order->createdAt = new \DateTime();

        foreach ($lines as $l) {
            $order->items[] = OrderItem::create($order, $l->productId(), $l->getName(), $l->quantity(), $l->price()->toMinor());
        }

        return $order;
    }
}

Application

Defines the system’s use cases through CommandHandler and QueryHandler.
A Handler is the single entry point for executing a use case:
- CommandHandler — for state changes (create, update, delete).
- QueryHandler — for retrieving data within the business context.
All commands and queries go through a Handler, which prevents bypassing business rules and ensures controlled execution paths.
A Handler coordinates domain objects and repositories, performs validation, and runs everything inside a transaction.
Because validation happens inside the Handler, data is always verified regardless of the entry point (HTTP, CLI, queue), ensuring consistent behavior across the system.

class CreateProductCommandHandler
{
    public function __construct(
        private ProductRepositoryInterface $productRepository,
        private CommandValidatorInterface $commandValidator,
        private TransactionRunnerInterface $transactionRunner
    ) {
    }

    public function __invoke(CreateProductCommand $command): Product
    {
        $this->commandValidator->assert($command);
        return $this->transactionRunner->run(function () use ($command) {
            $product = Product::create($command->id, $command->name, Money::fromMinor($command->price), $command->onHand);
            $this->productRepository->add($product);

            return $product;
        });
    }
}

Infrastructure

Technical details: Doctrine mappings, repository implementations, framework glue.
Implements ports defined by Application.

class ProductRepository implements ProductRepositoryInterface
{
    public function __construct(private readonly EntityManagerInterface $entityManager)
    {
    }

    public function get(string $productId): ?Product
    {
        return $this->entityManager->getRepository(Product::class)->findOneBy(['id' => $productId]);
    }

Presentation

Entry points: HTTP controllers, CLI commands.
Receives requests, validates input, builds a Command/Query, and calls a Handler.

Bounded Contexts Architecture

Order BC
Owns orders, statuses, and reservation workflow. Source of truth for Order and OrderItem. Integrates with Catalogue only via Contracts (OHS/ACL).

Catalogue BC
Owns products and stock. Source of truth for Product and Stock. Exposes APIs for stock reservation and fulfillment.

⸻

Data & Persistence Rules

Foreign keys only inside one BC. Cross-BC references are stored as IDs/values, never relational FKs.
Clear ownership. Only the owning BC mutates its data. Others consume via Contracts or projections.
No cross-BC transactions. An Order transaction commits first, then calls Catalogue OHS (HTTP/queue).

This ensures strict boundaries, stable contracts, and scalable microservice extraction.

Bounded Contexts Communication

Open Host Service (OHS)

The Catalogue BC exposes its functionality via an Open Host Service (OHS) - a public API for other contexts.

Defined in Contracts as interfaces and DTOs (Published Language).
Ensures stability of external integration even if Catalogue internals change.
Implemented in Infrastructure/Ohs.

Contract example:

namespace App\Catalogue\Contracts\Reservation;

interface CatalogueStockReservationPort
{
    public function reserve(CatalogueReserveStockRequest $request): CatalogueReservationResult;
}

Implementation (OHS Adapter):

namespace App\Catalogue\Infrastructure\Ohs;

use App\Catalogue\Application\Command\Handler\ReserveStockCommandHandler;
use App\Catalogue\Application\Command\ReserveStockCommand;
use App\Catalogue\Contracts\Reservation\CatalogueReservationResult;
use App\Catalogue\Contracts\Reservation\CatalogueStockReservationPort;
use App\Catalogue\Contracts\Reservation\CatalogueReserveStockRequest;

class CatalogueStockReservationService implements CatalogueStockReservationPort
{
    public function __construct(private ReserveStockCommandHandler $handler)
    {
    }

    public function reserve(CatalogueReserveStockRequest $request): CatalogueReservationResult
    {
        try {
            $command = new ReserveStockCommand($request->items);
            ($this->handler)($command);
            return CatalogueReservationResult::ok();
        } catch (\Throwable $e) {
            return CatalogueReservationResult::fail($e->getMessage());
        }
    }
}

Anti-Corruption Layer (ACL)

On the consumer side, Order BC integrates with Catalogue via an ACL:

Implements its own ports (StockReservationPort, etc.).
Delegates to Catalogue’s OHS Contracts.
Adapts responses into its own model without leaking foreign domain details.


namespace App\Order\Integration\Catalogue;

use App\Catalogue\Contracts\Reservation\CatalogueReserveStockRequest;
use App\Catalogue\Contracts\Reservation\CatalogueStockReservationPort;
use App\Order\Application\Port\Dto\ReservationRequest;
use App\Order\Application\Port\Dto\ReservationResult;
use App\Order\Application\Port\StockReservationPort;

readonly class StockReservationAdapter implements StockReservationPort
{
    public function __construct(private CatalogueStockReservationPort $reservation)
    {
    }

    public function reserve(ReservationRequest $request): ReservationResult
    {
        $catalogueRequest = new CatalogueReserveStockRequest(
            array_map(fn($i) => ['product_id' => $i['product_id'], 'quantity' => $i['quantity']], $request->items),
            ['order_id' => $request->orderId]
        );
        $reservationResult = $this->reservation->reserve($catalogueRequest);
        return $reservationResult->success ? ReservationResult::ok() : ReservationResult::fail($reservationResult->reason);
    }
}

Microservice-ready design

The Catalogue BC can be extracted into a standalone microservice with minimal changes:

Contracts stay stable — DTOs and ports define the published language, reused by both sides.
Domain & Application unchanged — business logic and use-cases move as-is.
Infrastructure adapters switch — OHS becomes an HTTP/queue endpoint in Catalogue; ACL in Order becomes an HTTP/queue client.

This design ensures you can scale from monolith to microservices by replacing only the transport layer, not rewriting core logic.

Deptrac: Enforcing architectural boundaries

In complex systems it’s easy to break DDD principles - for example, accidentally pulling Symfony or Doctrine into the Domain, or letting Presentation call repositories directly.
To prevent this, I use Deptrac as an automatic architectural linter.

Purpose of Deptrac

Protect the Domain and Application: no dependencies on Symfony, Doctrine, or infrastructure code.
Explicit layer boundaries: Presentation can only see Application, Application can only see Domain and Shared, and Domain depends exclusively on SharedDomain.
Control between bounded contexts: interaction between Order and Catalogue goes strictly through Contracts and ACL, never directly.
Documented rules: the deptrac.yml file serves as living documentation of the architecture.

Usage

Locally: vendor/bin/deptrac analyze deptrac.yml
In CI: every pull request is checked for boundary violations. If Presentation tries to access Domain directly, the build fails.
Result: the team always gets immediate feedback when someone attempts to bypass the architecture.

Full deptrac.yml: on GitHub

DDD Testing

In these projects I deliberately structure the test pyramid around business logic, keeping it isolated from frameworks and infrastructure. The main layers are:

Domain tests
- Focus on invariants and business rules.
- Executed completely isolated from the database, Symfony, or any technical dependencies.
- Examples: an Order cannot be created with a zero amount; a Product cannot have negative stock.

public function test_create_order_ok(): void
{
        $lines = [
            ['p1', 'Product 1', 1, 500],
            ['p2', 'Product 2', 2, 500],
        ];

        $order = Order::create(
            'ord-1',
            Money::fromMinor(1500),
            ...array_map(fn($l) => $this->line(...$l), $lines),
        );

        self::assertSame('ord-1', $order->getId());
        self::assertSame(1500, $order->getAmountToPay());

        $items = [...$order->getItems()];
        self::assertCount(count($lines), $items);

        foreach ($lines as $i => [$pid, , $qty, $price]) {
            $item = $items[$i];
            self::assertSame($pid, $item->getProductId());
            self::assertSame($qty, $item->getQuantity());
            self::assertTrue(Money::fromMinor($price)->equals($item->getPrice()));
        }
}

Application tests
- Verify Handlers as use cases - the single entry points into business logic.
- Cover: validation through the CommandValidatorInterface contract, execution within a transaction, repository interactions, and reaction to domain events or exceptions.
- Use in-memory adapters for repositories and transactions to stay independent of infrastructure.
- Ensure business scenarios remain consistent regardless of the runtime environment.

Framework and technical concerns (Symfony, Doctrine, transport adapters) are covered only by a thin layer of integration tests - limited to critical HTTP scenarios that verify correct request → command → response mapping.

Full tests: on GitHub

Summary

Pure Domain — business logic lives in clean entities and value objects, completely free from Symfony or Doctrine.
Application as a gateway — every use case runs through a Handler, ensuring validation, transactions, and orchestration are always consistent.
Clear boundaries — Bounded Contexts talk only via Contracts (OHS/ACL). No shortcuts, no leaking of internals.
Enforced architecture — Deptrac acts as an architectural linter, keeping the codebase aligned with DDD principles over time.
Layered testing — Domain and Application are tested in isolation, without frameworks, while only critical scenarios are verified end-to-end.

By combining these practices, the project stays maintainable under high domain complexity, and the architecture itself becomes part of the product’s quality and business value.

Explore full demo project: on GitHub

📬 Let’s Connect

If you’re looking for a senior developer to solve complex architecture challenges or lead critical parts of your product — let’s talk.

👉 Connect with me on LinkedIn

Laravel Livewire 3 Filter SEO and UI (Part 3)

Mykola Vantukh — Wed, 04 Jun 2025 06:30:17 +0000

In this third part of the series, we’ll dive into the role of JavaScript

Even though Livewire 3 already updates content without reloads, this small JavaScript bridge was essential for:

Updating the URL in the browser history as filters change
Keeping the page title and meta tags accurate for users
Ensuring back/forward navigation in the browser re-triggers Livewire updates

The goal: a seamless and consistent UX without full page reloads or a separate SPA framework.

The Purpose for Users

For users, this JavaScript ensures that:

When filters are applied, the page title and meta description change immediately in the browser tab.
The browser URL updates dynamically, so sharing links always reflects the current filter combination.
Clicking back/forward buttons updates the filters and product lists correctly, without any glitches.
No flickering or reloads – everything feels native and smooth.

The Minimal JS Bridge

export default class ProductsFiltersLivewire {
    constructor() {
        this.isInitialized = false;
    }

    init(baseUrl) {
        if (this.isInitialized) {
            return;
        }
        this.isInitialized = true;
        this.replaceHistoryState(baseUrl);
        this.setupEventListeners();
        this.setupLivewireHooks();
    }

    replaceHistoryState(baseUrl) {
        history.replaceState({ url: [baseUrl] }, null, baseUrl);
    }

    setupEventListeners() {
        window.addEventListener('popstate', (event) => {
            Livewire.dispatch('url-changed-back', event.state.url);
        });
    }

    setupLivewireHooks() {
        // Update browser URL as filters or pages change
        Livewire.on('url-updated', (url) => {
            history.pushState({ url: url }, null, url);
        });

        Livewire.on('page-changed', (url) => {
            history.pushState({ url: url }, null, url);
        });

        // Update meta tags and page heading instantly for a polished UX
        Livewire.on('meta-tags-ready-for-update', (data) => {
            document.title = data['meta_title'];

            const robotsMeta = document.querySelector('meta[name="robots"]');
            if (robotsMeta) robotsMeta.setAttribute('content', data['robots_content']);

            const descMeta = document.querySelector('meta[name="description"]');
            if (descMeta) descMeta.setAttribute('content', data['meta_description']);

            const canonicalLink = document.querySelector('link[rel="canonical"]');
            if (canonicalLink) canonicalLink.setAttribute('href', data['canonical_tag']);

            const pageHeading = document.querySelector('.pageHeadingTitle');
            if (pageHeading) pageHeading.textContent = data['page_heading_title'];
        });

        // Handle loading states for instant visual feedback
        Livewire.hook('commit', (interaction) => {
            this.handleCommit(interaction);
        });
    }

    handleCommit({ component, commit, respond, succeed, fail }) {
        this.setLoadingState(component.el, true);

        succeed(() => {
            this.setLoadingState(component.el, false);
        });

        fail(() => {
            this.setLoadingState(component.el, false);
        });
    }

    setLoadingState(el, loading) {
        if (loading) {
            el.classList.add("loading");
        } else {
            el.classList.remove("loading");
        }
    }
}

How It Interacts with Livewire

Livewire emits events like url-updated, meta-tags-ready-for-update, or lifecycle hooks (commit) whenever filters change, new products are loaded, or the page is rehydrated.

This JS bridge listens to those events and:

Updates the browser’s URL history
Dynamically updates meta tags and titles in the browser DOM
Manages loading states visually (e.g., a “loading” CSS class on filter panels or product areas)

Everything is driven by Livewire’s event system – the JS doesn’t do any data-fetching itself. It simply mirrors and finalizes what Livewire already did server-side.

Let’s Connect

If you’re looking for a senior developer to solve complex architecture challenges or lead critical parts of your product — let’s talk.

Connect with me on LinkedIn

Laravel Livewire 3 Filter Architecture (Part 2)

Mykola Vantukh — Wed, 04 Jun 2025 06:30:01 +0000

In this second part, I’ll walk you through the component architecture behind this solution — how I structured the Livewire components, delegated logic to services, and enabled event-driven communication across the system.

Livewire 3 in the Presentation Layer

It’s important to understand that Livewire 3 operates in the presentation layer of your application. It’s responsible for:

• Handling the user interface

• Synchronizing data with the backend

• Updating the page reactively without reloading the entire page

Common Pitfall: Bloated Components

Many developers mistakenly treat Livewire components as a place for business logic or data access.

While Livewire can directly access models and repositories, this leads to bloated, hard-to-maintain components.

Instead, treat Livewire as the bridge between the browser and your application logic:

Livewire (presentation layer)

Receives data
Renders views
Validates inputs
Dispatches events

Application layer (services, DTOs, queries)

Handles data fetching
Processes business rules
Performs calculations

Key Components

The system consists of three Livewire 3 components:

1️⃣ Filters – manages filter UI, SEO meta tags, and filter payload

2️⃣ Products – handles fetching product data and pagination

3️⃣ ProductsSummarize – displays a summary of the product count and reacts to product events

`Filters`: Responsibilities

The Filters component:

Parses filters from the current URL
Loads available filter options for the selected category
Maps selected filter values from the query
Transforms raw filters into a frontend-friendly structure
Dispatches SEO meta tag updates (title, description, canonical, robots)

Main Dependencies

public function boot(
    CategoryFiltersResolver $categoryFiltersResolver,
    FilterStateMapper $filterStateMapper,
    UrlFiltersParser $urlFiltersParser,
    FiltersToViewDataTransformer $viewDataTransformer,
    CurrentUrlFilterState $currentUrlFilterState,
    PageSeoDataProvider $pageSeoDataProvider
)

Each service has a single responsibility:

Service	Responsibility
`CategoryFiltersResolver`	Returns available filters for a given category
`FilterStateMapper`	Maps selected filters from query parameters
`UrlFiltersParser`	Extracts and sanitizes filter query groups from the URL
`FiltersToViewDataTransformer`	Converts raw filters into frontend-ready data
`CurrentUrlFilterState`	Holds current route and query state
`PageSeoDataProvider`	Generates SEO meta data: title, description, robots, canonical

Note:

PageSeoDataProvider plays a key role in this architecture:

It ensures that all SEO-related data — meta titles, H1 titles, robots index/noindex rules — are dynamically calculated on the server. These values adapt to the current filter state, the selected country, and other business-specific conditions, guaranteeing accurate and SEO-optimized output for each filter combination.

View code on GitHub Gist

`Products`: Responsibilities

The Products component:

Listens for events like filter-updated, page-changed, and sort-updated
Fetches the filtered product list and pagination data
Dispatches products-updated events to inform other components

Main Dependencies

public function boot(
    ProductsProvider $productsProvider,
    Pagination $paginationService,
    UrlFiltersParser $urlFiltersParser,
    LocalizationInfo $localizationInfo,
    CurrentUrlFilterState $currentUrlFilterState
)

Service	Responsibility
`ProductsProvider`	Fetches the filtered product collection
`Pagination`	Builds pagination structure for the current state
`UrlFiltersParser`	Parses the current URL query string
`LocalizationInfo`	Provides locale and country context
`CurrentUrlFilterState`	Holds the current route and query parameters

View code on GitHub Gist

`ProductsSummarize`: Responsibilities

The ProductsSummarize component is purely presentational:

It listens for products-loaded and products-updated events
It updates the summary bar in real-time based on those events

#[On('products-loaded')]
#[On('products-updated')]
public function updateSummarize(int $foundProducts, int $totalInCategory): void
{
    $this->foundProducts = $foundProducts;
    $this->totalProductsInCategory = $totalInCategory;
}

View code on GitHub Gist

Event-Driven Communication

My components don’t depend directly on each other. Instead, they communicate via Livewire events:

Component	Emits / Listens to	Purpose
`Filters`	Emits: `filter-updated`, `url-updated`, `meta-tags-ready-for-update`	Informs others of filter changes and SEO updates
`Products`	Listens to: `filter-updated`, `url-updated` Emits: `products-updated`	Loads new products and informs others about the updated list
`ProductsSummarize`	Listens to: `products-updated`	Updates summary data based on the latest product data

Why not use Livewire’s `#[Url]`?

Livewire’s #[Url] is excellent for simple reactive inputs (like search bars). However, for this project I needed:

Full control over canonical and localized URLs
Server-driven SEO meta data (title, canonical, robots)
Advanced rules (like noindex for certain filter combinations)
Structured filter state — not just flat query parameters

That’s why I implemented a dedicated UrlFiltersParser and SEO data services.

It’s more work — but it ensures perfect SEO, clean architecture, and no SSR/hydration issues.

Testing

All critical logic — filter parsing, product loading, and SEO meta data generation — lives in dedicated services. These services are fully covered by unit tests (e.g., PHPUnit).

For Livewire components, I rely on Livewire’s testing utilities to verify event dispatching and UI state updates.

Summary

This architecture delivers:

Loosely coupled, reusable components with a clear separation of UI and logic
Thin and reactive components — no bloated logic or hard dependencies
Dedicated, testable services that handle business logic (e.g., filter parsing, SEO generation)
Event-driven communication through Livewire events, ensuring no direct dependencies
Server-driven, indexable SEO data (title, canonical, robots) — safe for SSR and search engines
No frontend frameworks — no JavaScript duplication or hydration issues

In Part 3, I’ll explain the role of the JS bridge and how it supports a smooth, dynamic UI experience.

Let’s Connect

If you’re looking for a senior developer to solve complex architecture challenges or lead critical parts of your product — let’s talk.

Connect with me on LinkedIn

Laravel Livewire 3 SEO-Friendly Product Filter(Part 1)

Mykola Vantukh — Wed, 04 Jun 2025 06:29:49 +0000

📺 Demo:

The Problem

Recently, I faced the challenge of creating a product filter with full SEO indexing support.

The website was built as a multipage Laravel project, but one specific page — the product listing — needed to be fully reactive.
When users clicked on the filters, the following had to happen dynamically without a full page reload:

The list of products had to update based on the selected filters.
The URL, page title, and meta tags had to change to reflect the new filter state.
New filter URLs had to be generated so that each combination could be indexed by search engines.

This required a careful balance:
• Full SSR rendering for SEO and crawlers
• Smooth, reactive UX
• Avoid bloating the stack with a complex SPA framework

Filtering Implementation: Comparing Approaches

I compared several frontend strategies:

Approach	SSR-Compatible	SEO-Friendly	UX	Dev Complexity	Verdict
Full page reloads	✅ Yes	✅ Yes	❌ Poor UX	✅ Simple	❌ Unacceptable UX
Alpine + AJAX	❌ No	❌ No	✅ Good	✅ Simple	❌ Breaks SEO + SSR
Vue/Nuxt/Inertia	✅* Partial	✅/❌ Mixed	✅ Excellent	❌ High	❌ Overkill for one page
Livewire 3	✅ Yes	✅ Yes	✅ Excellent	✅ Moderate	✅ Best balance

⚠️ Why Vue/Nuxt Wasn’t the Right Fit

While Nuxt (or Inertia) can technically do SSR, it requires:

A separate Node server to handle SSR requests
Complex hydration pipelines
Custom routing sync between Laravel and frontend
Extra effort to generate localized meta tags

Too heavy for a single page. Too complex to maintain.

Why I Chose Livewire 3

After evaluating the options, Livewire 3 emerged as the best balance:

Full SSR support – no compromises on SEO
Seamless dynamic updates – updates the UI smoothly without full page reloads
No extra JS stack or Node server needed – stays within the Laravel ecosystem
Lean and maintainable – avoids bloating the stack with unnecessary complexity

This choice was crucial because I wanted to keep the Laravel ecosystem lean, avoiding unnecessary complexity for a single page, while ensuring that both SEO and UX remain first-class.

In Part 2, I’ll show you the filter architecture and its components.

Let’s Connect

If you’re looking for a senior developer to solve complex architecture challenges or lead critical parts of your product — let’s talk.

Connect with me on LinkedIn

Rich vs Anemic Entities in PHP with Doctrine: How to Structure Your Business Logic Right

Mykola Vantukh — Fri, 21 Mar 2025 14:08:29 +0000

Doctrine-Based Rich Entities in PHP: A Better Way to Model Business Logic

When building complex business applications, I follow one core principle:

Keep domain logic close to the domain, not spread across the application.

Instead of treating entities like simple data containers (the common Anemic Entities), I design Rich Entities — objects that encapsulate both state and behavior.

This approach allows me to:

Enforce business rules directly inside the model
Protect domain invariants
Build scalable, expressive, testable codebases

Let me show you exactly how I apply this in real-world PHP apps, using Doctrine ORM.

The Anemic Entity

In many PHP applications, entities are treated as plain data holders, while all logic is pushed to service classes.

<?php

use Doctrine\ORM\Mapping as ORM;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;

#[ORM\Entity]
#[ORM\Table(name: "orders")]
class Order
{
    #[ORM\Id]
    #[ORM\Column(type: "string")]
    #[ORM\GeneratedValue(strategy: "IDENTITY")]
    private string $id;

    #[ORM\Column(type: "integer")]
    private int $customer_id;

    #[ORM\Column(type: "decimal", precision: 10, scale: 2)]
    private float $amount_to_pay;

    #[ORM\Column(type: "datetime")]
    private DateTime $created_at;

    #[ORM\Column(type: "datetime", nullable: true)]
    private ?DateTime $fully_paid_at = null;

    #[ORM\ManyToOne(targetEntity: Customer::class)]
    #[ORM\JoinColumn(name: "customer_id", referencedColumnName: "id")]
    private Customer $customer;

    #[ORM\OneToMany(targetEntity: OrderPayment::class, mappedBy: "order", orphanRemoval: true, cascade: ["persist", "remove"])]
    private Collection $payments;

    public function __construct()
    {
        $this->payments = new ArrayCollection();
    }

    public function getId(): string
    {
        return $this->id;
    }

    public function getCustomerId(): int
    {
        return $this->customer_id;
    }

    public function getAmountToPay(): float
    {
        return $this->amount_to_pay;
    }

    public function getCreatedAt(): DateTime
    {
        return $this->created_at;
    }

    public function getFullyPaidAt(): ?DateTime
    {
        return $this->fully_paid_at;
    }

    public function getCustomer(): Customer
    {
        return $this->customer;
    }

    public function getPayments(): Collection
    {
        return $this->payments;
    }

    public function setCustomerId(int $customer_id): void
    {
        $this->customer_id = $customer_id;
    }

    public function setAmountToPay(float $amount_to_pay): void
    {
        $this->amount_to_pay = $amount_to_pay;
    }

    public function setCreatedAt(DateTime $created_at): void
    {
        $this->created_at = $created_at;
    }

    public function setFullyPaidAt(?DateTime $fully_paid_at): void
    {
        $this->fully_paid_at = $fully_paid_at;
    }

    public function setCustomer(Customer $customer): void
    {
        $this->customer = $customer;
    }

    public function setPayments(Collection $payments): void
    {
        $this->payments = $payments;
    }

    public function addPayment(OrderPayment $payment): void
    {
        $this->payments->add($payment);
    }
}

This leads to code that:

Is harder to test
Violates encapsulation
Spreads business rules across the application
Encourages duplication and brittle architectures

This approach is commonly used in architectures that prefer behavior-less entities, where all business logic is intentionally placed in application services. While this can work in some cases, it often results in fragmented, harder-to-maintain systems.

Let’s fix that.

The Rich Entity

Here's a simplified example of how I structure an Order aggregate using Doctrine ORM.

This is not just a database record — it's a business object with meaningful behavior.

<?php

use Doctrine\ORM\Mapping as ORM;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;

#[ORM\Entity]
#[ORM\Table(name: "orders")]
class Order
{
    #[ORM\Id]
    #[ORM\Column(type: "string")]
    #[ORM\GeneratedValue(strategy: "IDENTITY")]
    protected string $id;

    #[ORM\Column(type: "integer")]
    protected int $customer_id;

    #[ORM\Column(type: "decimal", precision: 10, scale: 2)]
    protected float $amount_to_pay;

    #[ORM\Column(type: "datetime")]
    protected DateTime $created_at;

    #[ORM\Column(type: "datetime", nullable: true)]
    protected ?DateTime $fully_paid_at = null;

    #[ORM\ManyToOne(targetEntity: Customer::class)]
    #[ORM\JoinColumn(name: "customer_id", referencedColumnName: "id")]
    private Customer $customer;

    #[ORM\OneToMany(targetEntity: OrderPayment::class, mappedBy: "order", orphanRemoval: true, cascade: ["persist", "remove"])]
    protected Collection $payments;

    protected function __construct()
    {
        $this->payments = new ArrayCollection();
    }

    public static function create(Customer $customer, float $amountToPay): self
    {
        if ($amountToPay <= 0.0) {
            throw new \InvalidArgumentException("Order amount must be greater than zero.");
        }

        $order = new self();
        $order->customer = $customer;
        $order->amount_to_pay = $amountToPay;
        $order->created_at = new DateTime();

        return $order;
    }

    public function pay(float $amount): OrderPayment
    {
        if ($amount <= 0.0) {
            throw new \InvalidArgumentException("Payment amount must be greater than zero.");
        }

        if ($this->isFullyPaid()) {
            throw new \LogicException("Order has already been fully paid.");
        }

        if ($amount > $this->amount_to_pay) {
            throw new \LogicException(
                sprintf("Invalid payment amount. Remaining amount to pay: %.2f", $this->amount_to_pay)
            );
        }

        $this->amount_to_pay -= $amount;

        $payment = OrderPayment::create($this, $amount);
        $this->payments->add($payment);

        if ($this->amount_to_pay === 0.0) {
            $this->fully_paid_at = new DateTime();
        }

        return $payment;
    }

    public function isFullyPaid(): bool
    {
        return $this->fully_paid_at instanceof DateTime;
    }

    public function getRemainingAmount(): float
    {
        return $this->amount_to_pay;
    }

    public function getFullyPaidAt(): ?DateTime
    {
        return $this->fully_paid_at;
    }

    public function getCustomer(): Customer
    {
        return $this->customer;
    }

    public function getPayments(): Collection
    {
        return $this->payments;
    }
}

That’s it.
This design aligns well with SOLID principles:

Single Responsibility Principle — entity governs its own rules
Open/Closed Principle — you can extend without modifying internals
Encapsulation — internal state is protected and validated

Why Not a Service Layer?

You could handle this logic through a service like:

class OrderPaymentService
{
    public function pay(Order $order, float $amount): OrderPayment
    {
        if ($amount <= 0.0) {
            throw new \InvalidArgumentException("Amount must be positive.");
        }

        if ($order->getFullyPaidAt() !== null) {
            throw new \LogicException("Order already fully paid.");
        }

        $remainingAmount = $order->getAmountToPay();
        if ($amount > $remainingAmount) {
            throw new \LogicException("Overpayment not allowed.");
        }

        $order->setAmountToPay($remainingAmount - $amount);

        $payment = OrderPayment::create($order, $amount);
        $order->addPayment($payment); // this method still makes sense in anemic model

        if ($order->getAmountToPay() === 0.0) {
            $order->setFullyPaidAt(new \DateTime());
        }

        return $payment;
    }
}

But this has several downsides:

Business logic is disconnected from the domain model
Logic gets duplicated and harder to test
Encapsulation is weak — the entity exposes its internal state through public setters like $order->setAmountToPay(), which allows any external code to change critical values without enforcing domain rules or ensuring consistency. This can easily lead to invalid business state — for example, setting amountToPay to zero without marking the order as fully paid or registering a payment
When you want to understand or change how an entity works, you must search for the service that “owns” its logic — like OrderPaymentService, OrderWorkflowManager, or some arbitrary class buried in the application layer. This leads to poor discoverability, tight coupling, and a fragile architecture where rules are duplicated or missed altogether. In contrast, Rich Entities encapsulate that behavior directly inside the model, so the code that changes entity state is co-located with the state itself — making the system more expressive, testable, and easier to reason about.

Rich Entities Are Easier to Test

Another practical benefit of Rich Entities is how much simpler and cleaner unit tests become.

Instead of testing service classes full of business logic, we can test behavior directly on the entity itself — with less boilerplate and better focus.

Testing a Rich Entity (Simple, Focused Unit Test)

public function test_order_can_be_fully_paid()
{
    $customer = $this->createStub(Customer::class);

    $order = Order::create($customer, 200.00);
    $payment1 = $order->pay(120.00);
    $payment2 = $order->pay(80.00);

    $this->assertTrue($order->isFullyPaid());
    $this->assertEquals(0.00, $order->getRemainingAmount());
    $this->assertCount(2, $order->getPayments());
    $this->assertInstanceOf(DateTime::class, $order->getFullyPaidAt());
}

Simple, expressive, domain-focused test
No mocks or infrastructure setup
Verifies business behavior directly

Testing Service-Class-Based Logic (More Setup, More Fragile)

public function test_service_can_pay_order()
{
    $customer = $this->createStub(Customer::class);
    $order = Order::create($customer, 200.00);

    $service = new OrderPaymentService();
    $payment1 = $service->pay($order, 120.00);
    $payment2 = $service->pay($order, 80.00);

    $this->assertEquals(0.00, $order->getAmountToPay());
    $this->assertCount(2, $order->getPayments());
    $this->assertInstanceOf(DateTime::class, $order->getFullyPaidAt());
}

More indirection

Business logic is harder to verify in isolation
Still coupled to internal entity state (setAmountToPay, setFullyPaidAt, etc.)

By keeping your business rules inside your entities, you naturally get simpler tests, better coverage, and cleaner architecture — without needing heavy mocks or complex setups.

Why I Use Static `create()` Methods

You’ll notice I don’t call new Order() directly. Instead, I use:

Order::create($customer, $amount);

Why?

Ensures entity is always created in a valid state
Prevents broken, incomplete, or invalid objects
Keeps initialization logic in one place
Improves code readability and reliability

Conclusion

Designing rich entities is not just a stylistic choice — it’s a strategic architectural decision that impacts clarity, maintainability, and scalability of your codebase.

Rich models shine when:

You have complex business rules and invariants to enforce
You want to reduce duplication across services and layers
You aim for clear, expressive APIs that reflect real-world actions ($order->pay() vs $orderService->payOrder($order, $amount))

That said, anemic models still have valid use cases:

In CRUD-heavy applications with little domain complexity
When you want to keep entities simple and defer all behavior to services
In team environments where DDD is not a shared mindset or priority

And yes, services still matter — but ideally, they should orchestrate use cases, not own the business logic.

A thin service layer coordinating rich domain models is often the sweet spot:

Services handle application flow and infrastructure concerns
Entities handle core domain behavior and validation

So next time you’re building a feature, ask yourself:

“Is this a domain rule, or just a workflow orchestration?”

“Does this logic belong in a service — or should the entity own it?”

Use the right tool for the job — but always be intentional about where your business logic lives.

📬 Let’s Connect

If you’re looking for a senior developer to solve complex architecture challenges or lead critical parts of your product — let’s talk.

👉 Connect with me on LinkedIn

DEV Community: Mykola Vantukh

DDD with Symfony 7: Clean Architecture and Deptrac boundaries

Domain-Driven Design (DDD) in PHP projects

Architecture Layers

Bounded Contexts Architecture

Bounded Contexts Communication

Deptrac: Enforcing architectural boundaries

DDD Testing

Laravel Livewire 3 Filter SEO and UI (Part 3)

The Purpose for Users

The Minimal JS Bridge

How It Interacts with Livewire

Laravel Livewire 3 Filter Architecture (Part 2)

Livewire 3 in the Presentation Layer

Common Pitfall: Bloated Components

Key Components

Filters: Responsibilities

Main Dependencies

Products: Responsibilities

Main Dependencies

ProductsSummarize: Responsibilities

Event-Driven Communication

Why not use Livewire’s #[Url]?

Testing

Summary

Laravel Livewire 3 SEO-Friendly Product Filter(Part 1)

The Problem

Filtering Implementation: Comparing Approaches

⚠️ Why Vue/Nuxt Wasn’t the Right Fit

Why I Chose Livewire 3

Rich vs Anemic Entities in PHP with Doctrine: How to Structure Your Business Logic Right

Doctrine-Based Rich Entities in PHP: A Better Way to Model Business Logic

The Anemic Entity

The Rich Entity

Why Not a Service Layer?

Rich Entities Are Easier to Test

Why I Use Static create() Methods

Conclusion

`Filters`: Responsibilities

`Products`: Responsibilities

`ProductsSummarize`: Responsibilities

Why not use Livewire’s `#[Url]`?

Why I Use Static `create()` Methods