DEV Community: Mykola Vantukh

Preventing Race Conditions in Symfony with Doctrine and PostgreSQL

Mykola Vantukh — Sun, 27 Sep 2026 20:31:35 +0000

Two requests reserve the last available seat. Two workers decrement the same stock quantity. Two administrators update the same order.

Each operation can work correctly on its own and still produce an incorrect result when executed concurrently. In Symfony applications using Doctrine, the solution requires coordinating database access and making sure the ORM exposes the state that was actually locked.

This article uses seat reservations as an example, but the same approach applies to inventory, balances and guarded status transitions.

Scope: PostgreSQL at READ COMMITTED. Code snippets are simplified; links point to concrete implementations in a repository.

Here is the race the following sections will address:

Waiting for a row lock does not repeat the application's earlier availability check.

The core rule is:

Protect the whole decision: Read current state under the chosen concurrency mechanism, validate the invariant, and commit the corresponding changes together.

Different operations need different mechanisms. Before looking at pessimistic locking in detail, it helps to have the overall decision model:

Problem	Typical mechanism
Read current state, validate several conditions, then modify	Pessimistic locking with `SELECT ... FOR UPDATE`
Perform a simple guarded state transition	Conditional `UPDATE`
Handle edits spanning multiple HTTP requests	Optimistic locking
Prevent concurrent creation of the same logical record	`UNIQUE` constraint or primary key with `ON CONFLICT`

The rest of the article explains why these mechanisms solve different concurrency problems and what Doctrine adds on top of PostgreSQL's behavior.

Why a transaction alone is not enough

Consider a typical read–check–write operation:

$seat = $seatRepository->find($seatId);

if (!$seat->isAvailable()) {
    throw new SeatNotAvailableException($seatId);
}

$seat->holdFor($reservationId);
$entityManager->flush();

Two requests can both read AVAILABLE before either writes its change:

Step	Request A	Request B
1	Reads AVAILABLE	Reads AVAILABLE
2	Availability check passes	Availability check passes
3	Updates owner to A	Waits to update the same row
4	Commits	Updates owner to B and commits

Wrapping this code in a transaction makes each operation atomic, but does not prevent both availability checks from passing.

PostgreSQL serializes the writes. However, an update with only WHERE id = :id can still overwrite the previous owner: its condition remains true after waiting. The application made its business decision using an earlier state. This follows PostgreSQL's READ COMMITTED behavior.

Key rule: Protect the availability check together with the write.

Pessimistic locking: protect the entire decision

For a short operation that reads an entity, validates its state and updates it, Doctrine provides LockMode::PESSIMISTIC_WRITE.

On PostgreSQL, a locking query uses SELECT ... FOR UPDATE. A competing transaction requesting the same lock waits until the current holder commits or rolls back.

Service: define the transaction boundary

The transaction belongs around the entire use case. A simplified service method looks like this:

public function reserve(
    string $showId,
    string $seatId,
    string $reservationId,
): void {
    $this->entityManager->wrapInTransaction(function () use (
        $showId, $seatId, $reservationId,
    ): void {
        $seat = $this->seatRepository->findForUpdate($showId, $seatId);

        if ($seat === null || !$seat->isAvailable()) {
            throw new SeatNotAvailableException($seatId);
        }

        $seat->holdFor($reservationId);
    });
}

wrapInTransaction() flushes before committing. The transaction must already be active when the locking query executes; adding a lock to an ordinary repository call outside a transaction is insufficient.

The controller only calls the service and maps the result to HTTP. This keeps the same transaction boundary usable from HTTP, CLI and Messenger handlers.

Keep external HTTP calls and other slow work outside the locked section.

Repository: acquire the lock

The repository method contains the locking query:

use Doctrine\DBAL\LockMode;
use Doctrine\ORM\Query;

public function findForUpdate(string $showId, string $seatId): ?Seat
{
    return $this->createQueryBuilder('s')
        ->andWhere('s.id = :seatId')
        ->andWhere('IDENTITY(s.show) = :showId')
        ->setParameter('seatId', $seatId)
        ->setParameter('showId', $showId)
        ->getQuery()
        ->setLockMode(LockMode::PESSIMISTIC_WRITE)
        ->setHint(Query::HINT_REFRESH, true)
        ->getOneOrNullResult();
}

When request A commits a hold, request B acquires the lock and checks the held state. If A rolls back, B can acquire the still-available seat.

Code examples: locking query and service transaction boundary.

Doctrine can still hold an outdated entity

The query above includes Query::HINT_REFRESH for a reason.

Doctrine maintains an identity map: within one EntityManager, an entity identity normally corresponds to the same PHP object. If that object was loaded earlier, executing another query does not normally replace its fields with the returned database values.

Consider this sequence:

The current EntityManager loads a seat as AVAILABLE.
Another transaction changes it to HELD and commits.
The current EntityManager executes a locking query for that seat.

The database returns the current locked row, while Doctrine can retain the previously managed object:

PostgreSQL row:  HELD
PHP object:      AVAILABLE

The lock protects the row, but the availability check can still use stale state.

HINT_REFRESH makes Doctrine refresh an already managed entity from the query result. This is documented in Doctrine's query hints.

Refresh before modifying: Refreshing can overwrite unflushed changes. If the entity is being loaded for the first time, there is no earlier managed state to replace.

A refreshing locking query should therefore be treated as an acquisition boundary for the aggregate: acquire the lock and load the current state before making changes. Avoid calling such a query after modifying the same managed entity unless discarding those unflushed modifications is intentional.

Acquire the lock → hydrate current state → validate → modify → commit.

Locking after an earlier availability check leaves the race open.

Multiple rows: consistent lock order

When one operation needs several rows, acquire pessimistic locks in a consistent order. Different acquisition orders can cause a deadlock:

Transaction A: locks seat 1, waits for seat 2
Transaction B: locks seat 2, waits for seat 1

Every competing code path must follow the same order. Sorting IDs in PHP only helps if the repository actually acquires locks in that sequence; the order of values inside SQL IN (...) does not guarantee it.

Consistent ordering reduces deadlocks for this resource set but does not eliminate transaction-level deadlocks involving other resources.

Code example: ordered lock acquisition.

Limit how long a request waits for a lock

Choose a lock_timeout within the operation's latency budget and apply it with SET LOCAL inside the transaction.

A lock timeout means the operation could not acquire a lock in time; it does not establish that the seat is unavailable.

The timeout also applies to locks acquired implicitly by UPDATE and INSERT, including the alternative strategies below.

Choose the concurrency strategy for the operation

Pessimistic locking is useful when a short transaction needs to inspect current entities before changing them. It is not the only option.

Conditional UPDATE: simple state transitions

For a simple state transition, move the precondition into the write:

UPDATE seats
SET state = 'HELD',
    held_by_reservation_id = :reservationId
WHERE id = :seatId
  AND state = 'AVAILABLE';

With Doctrine DBAL, inspect the affected-row count. One changed row means the transition succeeded; zero means the seat was missing or unavailable.

For a multi-row operation, compare the count with the number of unique requested IDs and roll back partial changes before committing.

Conditional updates still acquire locks and can wait. Direct SQL also bypasses Doctrine's managed state, so avoid making subsequent decisions from entities that have become stale.

Optimistic locking: edits spanning HTTP requests

Optimistic locking is another choice when conflicts are infrequent, especially for edits spanning user interaction.

With a #[ORM\Version] field, Doctrine checks the entity's version against the database when updating it at flush and raises OptimisticLockException on a mismatch.

The application then needs an explicit conflict response or retry policy. Do not hold a database transaction open while a user edits a form.

See Doctrine's locking support.

For edits spanning HTTP requests, preserve the version originally shown to the user and check that expected version when processing the submission, for example:

$entityManager->lock(
    $entity,
    LockMode::OPTIMISTIC,
    $expectedVersion,
);

Loading the latest entity on submission and relying only on the check at flush can still overwrite changes made while the form was open.

See Doctrine's optimistic-locking implementation notes.

Concurrent INSERT: let a unique key decide

What if the row does not exist yet?

At READ COMMITTED, a SELECT ... FOR UPDATE that finds no row does not reserve that key. Two requests can both pass an existence check and attempt an insert.

Define what makes the record unique with a UNIQUE constraint or PRIMARY KEY, then handle the expected duplicate with ON CONFLICT:

INSERT INTO inbox_messages (
    consumer_name,
    message_id,
    message_type,
    processed_at
)
VALUES (
    :consumerName,
    :messageId,
    :messageType,
    :processedAt
)
ON CONFLICT (consumer_name, message_id) DO NOTHING;

Here, (consumer_name, message_id) is the primary key.

With DBAL's executeStatement(), inspect the affected-row count:

1: this transaction inserted the claim and can process the message.
0: the claim already exists; skip duplicate processing.

If another transaction is inserting the same key, PostgreSQL can wait for its outcome. If it commits, the waiting insert skips the duplicate; if it rolls back, the waiting insert can succeed.

One transaction: Commit the claim and the handler's database changes together, using the same connection. Otherwise, a committed claim followed by failed processing could make retries skip unfinished work.

DO NOTHING handles this expected conflict without a unique-violation error.

Use DO UPDATE when updating the existing record is the intended behavior.

Neither option automatically validates whether duplicate requests carry the same payload.

See PostgreSQL's ON CONFLICT documentation.

Code example: InboxMessageStore::claim() returns whether the insert succeeded; the middleware invokes the handler only for a successful claim.

Handle contention and transaction failures

Not every conflict should be retried. A seat that is already held is a valid business outcome; a lock timeout or deadlock is a transient infrastructure failure.

For transient failures, retry the entire transaction, not only the failed statement. After rollback, start from a fresh Doctrine EntityManager and reload the current state.

Keep retries bounded and within the request's latency budget. Repeated immediate retries can increase contention, so use a small retry limit with backoff and monitor lock waits, deadlocks and exhausted retries.

Final rule

Transactions, row locks, version fields and unique constraints solve different parts of the concurrency problem.

The important part is not choosing the most powerful mechanism. It is choosing the mechanism that protects the invariant at the point where the decision is made.

Protect the whole decision: Read current state under the chosen concurrency mechanism, validate the invariant, and commit the corresponding changes together.

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

Preventing Race Conditions in Symfony with Doctrine and PostgreSQL

Why a transaction alone is not enough

Pessimistic locking: protect the entire decision

Service: define the transaction boundary

Repository: acquire the lock

Doctrine can still hold an outdated entity

Multiple rows: consistent lock order

Limit how long a request waits for a lock

Choose the concurrency strategy for the operation

Conditional UPDATE: simple state transitions

Optimistic locking: edits spanning HTTP requests

Concurrent INSERT: let a unique key decide

Handle contention and transaction failures

Final rule

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