• Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
• Also by me: Database Playbook: Choosing the Right Store for Every System You Build
• My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
• Me: xgabriel.com | GitHub

A PlaceOrder use case is sitting on your screen. It writes the order. It reserves stock. It records a ledger entry. Three repositories, three writes, one business intent. If the ledger write fails, the order and the reservation have to vanish with it. Anything less, and a customer ends up with stock held against an order that does not exist.

You know the word for what you need. Atomicity. The database has known it for fifty years. So you reach for the obvious tool.

public function execute(PlaceOrderInput $input): PlaceOrderOutput
{
    return $this->entityManager->wrapInTransaction(
        function () use ($input) {
            $order = Order::place(/* ... */);
            $this->orders->save($order);
            $this->reservations->reserve(/* ... */);
            $this->ledger->record(/* ... */);
            return new PlaceOrderOutput($order->id->value);
        }
    );
}

It works. Tests go green, code review nods it through, you move on to the next ticket.

You also just made a mistake. The use case now imports Doctrine\ORM\EntityManagerInterface. The application layer, the part you were supposed to keep ignorant of the database, has Doctrine in its constructor. Every other use case will copy the pattern, because copy-paste is how patterns spread. Three months from now the application has dozens of references to EntityManager and one of your engineers is asking if you can move a slice of the system to MongoDB.

You cannot. Not cheaply.

This post is about getting atomicity without paying that price.

What the problem actually is

Transactions are an infrastructure concept. They live in the database, the driver, the ORM. The application layer needs the guarantee (all writes succeed together or none do) but it does not need the mechanism. The Dependency Rule says outer rings depend inward; inner rings know nothing of the outer. A PlaceOrder that calls EntityManager::wrapInTransaction inverts that. The use case is reaching outward into Doctrine.

The cost shows up first in testability. Every test for PlaceOrder now needs a real or mocked EntityManager. The unit tests with in-memory repositories and no database at all stop being unit tests. They become integration tests with extra steps.

It also shows up in portability. The word makes the problem sound grander than it is. "Switch ORMs" reads like something only architects in slide decks worry about. The real version is smaller. You want to run a use case from a CLI script against raw DBAL. You want a worker process that wires Doctrine differently. You want a test harness that runs the use case against an in-memory state machine. All of those break when EntityManager is welded to the use case.

You want the guarantee without the import.

Option 1: a UnitOfWork port

You write an interface in the application layer that expresses the transaction boundary in your own vocabulary. The implementation lives at the edge.

<?php

declare(strict_types=1);

namespace App\Application\Port;

interface UnitOfWork
{
    /**
     * @template T
     * @param callable(): T $work
     * @return T
     */
    public function wrap(callable $work): mixed;
}

One method. The contract is plain: run the callable, and if it returns, the writes are durable; if it throws, the writes are undone and the exception propagates.

Notice what is missing. No begin, no commit, no rollback. Those exist in the adapter. The application never sees them, because there is no reasonable case for application code to start a transaction without also being responsible for ending it. You can construct hypotheticals, but they tend to dissolve back into a design smell once you look closely.

The Doctrine adapter is six lines.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence\Doctrine;

use App\Application\Port\UnitOfWork;
use Doctrine\ORM\EntityManagerInterface;

final readonly class DoctrineUnitOfWork implements UnitOfWork
{
    public function __construct(
        private EntityManagerInterface $em,
    ) {}

    public function wrap(callable $work): mixed
    {
        return $this->em->wrapInTransaction(
            static fn () => $work(),
        );
    }
}

wrapInTransaction is the Doctrine 3 successor to the deprecated transactional. It opens a transaction on the underlying DBAL connection, runs the callable, flushes the EntityManager, commits on clean return, and on exception rolls back, closes the EntityManager, and re-throws the original error.

The Laravel adapter is also six lines (it calls DB::transaction($work)). The Symfony version wraps a Connection::transactional. You can write a PDO-only version that calls beginTransaction, commit, rollBack by hand. Same port, four different adapters, zero changes in the application layer.

The downside: you wrote and now maintain a port. One more file, one more abstraction in the stack trace.

The upside is bigger than it looks. The port composes with a decorator, and that is where the real win lives.

Option 2: a transactional decorator at the wiring level

The use case stays exactly as it was on the day you wrote it, before you knew transactions existed. It takes its repositories. It calls them. It returns. The transaction is composed at the boundary.

<?php

declare(strict_types=1);

namespace App\Application\Decorator;

use App\Application\Port\UnitOfWork;
use App\Application\UseCase;

final readonly class TransactionalDecorator implements UseCase
{
    public function __construct(
        private UseCase $inner,
        private UnitOfWork $unitOfWork,
    ) {}

    public function execute(mixed $input): mixed
    {
        return $this->unitOfWork->wrap(
            fn () => $this->inner->execute($input),
        );
    }
}

That is the whole class. It is the decorator pattern from the Gang of Four book, applied to use cases. The decorator implements the same interface as the thing it wraps, holds an instance of that thing, and adds behavior around the inner call. Here the added behavior is a transaction.

In the container, you bind PlaceOrder::class to a factory that builds the inner PlaceOrder and wraps it.

$inner = new PlaceOrder($orders, $reservations, $ledger);
$useCase = new TransactionalDecorator(
    $inner,
    $unitOfWork,
);

Callers ask the container for a PlaceOrder and get a decorated one. They do not know. They should not care. The HTTP controller, the CLI command, the queue worker all receive the same wrapped instance.

This is the option to reach for first, mostly because of what it prevents. PlaceOrder has no UnitOfWork in its constructor, so it cannot accidentally call begin and forget to call commit. It cannot half-commit a transaction by catching an exception it should not have caught. The boundary is enforced by composition, not by discipline (which, given enough engineers and enough deadlines, always loses).

Decoration also composes. You can stack a LoggingDecorator, a MetricsDecorator, a RetryDecorator, and a TransactionalDecorator in whatever order makes sense:

$inner       = new PlaceOrder($orders, $reservations, $ledger);
$transacted  = new TransactionalDecorator($inner, $unitOfWork);
$retried     = new RetryDecorator($transacted, maxAttempts: 3);
$metered     = new MetricsDecorator($retried, $metrics);
$logged      = new LoggingDecorator($metered, $logger);

Logging usually wraps the whole thing because you want to see the call even when the transaction rolled back. Retries wrap the transactional decorator so each retry is its own transaction. Metrics record either side depending on what you want to measure. The use case stays one class with one responsibility, and the cross-cutting concerns live as siblings around it.

Where the pattern frays: long-running operations (a six-second report, an external API call that takes its time) should not be inside a database transaction, so they should not be decorated. Distributed transactions across two databases are not what the decorator gives you; it wraps one connection.

Those cases need different machinery. For everything else, the port-plus-decorator pair is the answer.

Option 3: the pragmatic one — let the application know Doctrine flushes

You see this in production Laravel and Symfony codebases that have not yet adopted hexagonal architecture, or have adopted it partially. The use case calls $this->entityManager->flush() at the end, and a higher-level controller or middleware opens the transaction.

public function execute(PlaceOrderInput $input): PlaceOrderOutput
{
    $order = Order::place(/* ... */);
    $this->orders->save($order);
    $this->reservations->reserve(/* ... */);
    $this->ledger->record(/* ... */);
    $this->entityManager->flush();

    return new PlaceOrderOutput($order->id->value);
}

This works. Doctrine batches the writes until flush. If you opened a transaction at the controller level (or relied on wrapInTransaction somewhere above), the flush either commits or rolls back as one unit. You skipped writing a port. You have one less interface to teach to new hires.

The cost is that "the application calls flush" is now part of the contract. flush is a Doctrine method. Your application layer imports EntityManagerInterface. You traded a port for a leak. If you ever swap Doctrine out (a CQRS write side that uses raw DBAL, a different ORM, a test harness) every use case that calls flush is now framework-coupled and has to change.

For a single-team service that will live and die on Doctrine, this approach is fine. For a service that you expect to outlive its current persistence stack, it is debt that you will pay later.

It is included here because pretending it does not exist would misrepresent what runs in production. Plenty of working systems use it. Use it with eyes open.

Rollback semantics worth being precise about

When the adapter rolls back, here is what actually happens.

The database transaction reverses. Every INSERT, UPDATE, and DELETE issued inside the wrapped callable is gone as if it never happened.

The EntityManager is closed. Doctrine's identity map is in a known-bad state after a rollback (it may still hold managed entities that no longer exist in the database) so the ORM defensively shuts the EntityManager. If you wire the EntityManager as a long-lived singleton, handle reset between requests, or use a factory that returns a fresh instance after each rollback. Most modern frameworks handle this automatically when EM lifetime is scoped per request.

The exception keeps its identity. A DomainException thrown from the inner use case arrives at the outer caller as the same DomainException, not wrapped, not transformed. Domain exceptions cross the boundary unchanged so the HTTP adapter can translate them properly. The UnitOfWork port does not catch and rethrow, it does not wrap; it lets the exception go past it on the way out.

The application code at the controller level sees a clean picture. Either $useCase->execute($input) returned a value, in which case the writes are committed, or it threw, in which case they are not. No "partially committed," no "succeeded but didn't flush." That binary is the guarantee you were after when you started reaching for transactions in the first place.

Nested transactions: do not

You will eventually find yourself with a use case that calls another use case. Both are wrapped in TransactionalDecorator. What happens?

The Doctrine answer is technically savepoints. wrapInTransaction detects an open transaction on the underlying connection and uses a savepoint for the nested call. The outer transaction owns the real commit. The inner savepoint can roll back independently.

The practical answer: do not rely on this. Savepoints are not free; they generate extra round-trips and locks. Their semantics across database engines are not uniform. Postgres behaves differently from MySQL, which behaves differently from SQLite. Your test infrastructure may not reproduce production behavior. And worse, nested transactional use cases usually mean you have a composition problem: an "orchestrator" use case that should probably be split, or a use case calling another use case directly when it should be emitting an event.

One transaction boundary per inbound call. The controller invokes one decorated use case. That use case may internally call domain services, may emit domain events, may write to multiple repositories, but it stays inside the one transaction the decorator opened. If you need cross-aggregate work that cannot fit, you do not nest. You decompose, and the second operation runs in its own transaction, triggered by an event.

A reflection test that keeps the boundary honest

Architectural rules you do not enforce in code tend to drift, and the drift is invisible until you trip over it during a refactor. The smallest possible enforcement for "the application layer does not know about transactions" is a reflection test.

<?php

declare(strict_types=1);

namespace Tests\Architecture;

use App\Application\UseCase\PlaceOrder\PlaceOrder;
use PHPUnit\Framework\TestCase;
use ReflectionClass;

final class PlaceOrderIsTransactionAgnosticTest extends TestCase
{
    public function test_does_not_depend_on_transaction_machinery(): void
    {
        $forbidden = [
            'EntityManager',
            'wrapInTransaction',
            'beginTransaction',
            '->flush(',
            'commit(',
            'rollBack',
        ];

        $source = file_get_contents(
            (new ReflectionClass(PlaceOrder::class))
                ->getFileName(),
        );

        foreach ($forbidden as $token) {
            self::assertStringNotContainsString(
                $token,
                $source,
                sprintf(
                    'PlaceOrder leaked persistence concern: %s',
                    $token,
                ),
            );
        }
    }
}

The next engineer who reaches for the obvious-but-wrong solution sees this test fail in CI before the pull request gets a human reviewer. Steal it. Adapt it. Add similar guards for the other invariants you care about.

The honest trade-off

The decorator-plus-port approach is what most production codebases that have lived through a framework migration end up with, but it is not free.

The bill: one extra class per cross-cutting concern (the decorator), one extra interface for the port, plus DI configuration to bind them together. Every framework has its own dialect (Symfony's decoration tags, Laravel's app->bind callbacks, raw containers' factories). Stack traces from a wrapped use case include the decorator frame. That makes debugging marginally noisier. New engineers need to be told why a class named PlaceOrder is actually a TransactionalDecorator at runtime, because their IDE does not show that.

The pragmatic approach is faster to write and easier to explain on day one. $em->flush() at the bottom of every use case is two words. Anyone who knows Doctrine reads it instantly. No port, no decorator, no DI gymnastics. The cost is invisible until the day you want to evolve away from Doctrine, and by then the cost is dozens of files.

The middle ground (the port without the decorator) exists but is weakly motivated. If the port is already written, the decorator is free. Spreading $this->unitOfWork->wrap(...) calls across every use case when one decorator handles it once gains nothing. The only situation where the bare port makes sense is when some use cases need to not be transactional (long-running reports, idempotent reads), in which case you decorate the ones that need it and leave the rest alone.

Pick based on the lifespan you expect from the application. Code that will exist for three years and then be replaced: pragmatic. Code that you expect to keep running for a decade through framework upgrades and ORM migrations: port plus decorator.

What the use case never knew

Step back and notice what you built.

PlaceOrder is forty-something lines. It takes three repositories, calls them, returns. No transaction code, no ORM imports, no awareness of when a flush happens or what driver underpins the storage.

It is also fully atomic in production, fully testable without a database, and free to be wired into a CLI script, a queue worker, an HTTP controller, or a test harness with no changes. The behavior you wanted (all writes succeed together or none do) sits one layer above the class. That layer is the decorator. The decorator delegates to a port. The port has two implementations: one for Doctrine, one for tests.

If next year you replace Doctrine with raw DBAL, you write a new adapter and PlaceOrder does not change. Add MongoDB for some aggregates the year after, and you write a third adapter that holds a session and uses Mongo's transactional API; the use case still does not notice.

Transactions feel inherently database-y, which is why people stop trying to abstract them. The abstraction is small: a port, an adapter, and a decorator. You can have atomicity and decoupling at the same time. The cost is three files.

If this was useful

This is one chapter from Decoupled PHP — the book about treating Laravel or Symfony as an adapter and writing the rest of your application against ports it owns. The transaction chapter pairs with a chapter on the outbox pattern for the cases where one transaction is not enough, and a chapter on testing the hexagon without booting a container. If you want the database side of the story (picking the right store, designing schemas that survive growth, the actual trade-offs across Postgres, MySQL, MongoDB, DynamoDB) the Database Playbook is the companion volume.

Available on Kindle, Paperback, and Hardcover. English, German, and Japanese editions out now — Portuguese and Spanish coming soon.