DEV Community: Gabriel Anhaia

Named Constructors in PHP: Why Order::place() Beats new Order(...)

Gabriel Anhaia — Tue, 19 May 2026 19:53:18 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Thinking in Go (2-book series) — Complete Guide to Go Programming + Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You open a pull request and the first line of the diff is this:

$order = new Order(
    $customer,
    $items,
    OrderStatus::Pending,
    $now,
    null,
    null,
    null,
);

You read it three times. What does it mean? Is this a new checkout? An order being rehydrated from the database? An order cloned from a quote? The constructor will not tell you. It takes seven arguments, two of them are null, and the name of the method is __construct, a name PHP picked, not the domain.

The constructor is the worst place in your codebase to express intent. It is anonymous by language design. Every path that creates an Order calls the same opaque new Order(...), crams whatever it has into a positional argument list, and the defaults eventually turn into nulls.

Six months in, nobody on the team can read the call site without ctrl-clicking into the class.

The fix is older than PHP 8 and well documented in the DDD literature, but it still surprises people every time. Make the constructor private. Add named factories. The class now has verbs.

What the positional constructor is hiding

A typical Order class accumulates fields the same way a kitchen drawer accumulates batteries. Each new feature adds one parameter:

final class Order
{
    public function __construct(
        public readonly OrderId $id,
        public readonly CustomerId $customerId,
        public readonly array $items,
        public OrderStatus $status,
        public readonly DateTimeImmutable $placedAt,
        public ?QuoteId $sourceQuoteId = null,
        public ?DateTimeImmutable $confirmedAt = null,
        public ?DateTimeImmutable $cancelledAt = null,
    ) {}
}

Three problems compound. First, the constructor accepts states that should not coexist. An order with status = Pending and a non-null confirmedAt is a bug, but the constructor allows it. Second, every caller has to know which nulls to pass. The HTTP handler and the Doctrine hydrator and the unit test all call the same anonymous entry point, even though they are doing different things. Third, the name Order carries zero information about which lifecycle stage you are in.

The signature tells you how many fields exist. It tells you nothing about what an Order actually is.

Three things the same class actually does

Step back from the constructor and ask the domain. An Order is created in three distinct ways, and the differences matter:

A customer places a new order from a cart. Identity is generated. Status starts at Pending. placedAt is now. No sourceQuoteId, no confirmedAt, no cancelledAt. Invariants must run: the cart cannot be empty, the customer must exist, the total must be non-negative.
Doctrine reconstitutes an order from a row. Every field already exists. Nothing is computed. Nothing is validated — the row already passed validation when it was first written. The job is to put the bytes back in the right shape.
A customer places an order derived from a saved quote. Identity is generated. Status starts at Pending. sourceQuoteId is set. Items come from the quote, not the cart. A different invariant runs: the quote must not be expired.

These are three verbs: place, reconstitute, placeFromQuote. They are not three values for one constructor flag. Different inputs. Different invariants. Different outputs. The language already has a way to express that: methods with names.

The named-constructor pattern in PHP 8.3

Make __construct private. Add static factories. Each factory becomes a documented entry point with its own argument list and its own invariants.

<?php

declare(strict_types=1);

namespace App\Order\Domain;

use DateTimeImmutable;

final class Order
{
    private function __construct(
        public readonly OrderId $id,
        public readonly CustomerId $customerId,
        public readonly array $items,
        public OrderStatus $status,
        public readonly DateTimeImmutable $placedAt,
        public readonly ?QuoteId $sourceQuoteId,
        public ?DateTimeImmutable $confirmedAt,
        public ?DateTimeImmutable $cancelledAt,
    ) {}

    public static function place(
        CustomerId $customerId,
        array $items,
        DateTimeImmutable $now,
    ): self {
        if ($items === []) {
            throw new EmptyCart();
        }
        foreach ($items as $item) {
            if (!$item instanceof LineItem) {
                throw new InvalidLineItem();
            }
        }

        return new self(
            id: OrderId::generate(),
            customerId: $customerId,
            items: $items,
            status: OrderStatus::Pending,
            placedAt: $now,
            sourceQuoteId: null,
            confirmedAt: null,
            cancelledAt: null,
        );
    }

    public static function placeFromQuote(
        Quote $quote,
        DateTimeImmutable $now,
    ): self {
        if ($quote->isExpired($now)) {
            throw new QuoteExpired($quote->id());
        }

        return new self(
            id: OrderId::generate(),
            customerId: $quote->customerId(),
            items: $quote->items(),
            status: OrderStatus::Pending,
            placedAt: $now,
            sourceQuoteId: $quote->id(),
            confirmedAt: null,
            cancelledAt: null,
        );
    }

    public static function reconstitute(
        OrderId $id,
        CustomerId $customerId,
        array $items,
        OrderStatus $status,
        DateTimeImmutable $placedAt,
        ?QuoteId $sourceQuoteId,
        ?DateTimeImmutable $confirmedAt,
        ?DateTimeImmutable $cancelledAt,
    ): self {
        return new self(
            id: $id,
            customerId: $customerId,
            items: $items,
            status: $status,
            placedAt: $placedAt,
            sourceQuoteId: $sourceQuoteId,
            confirmedAt: $confirmedAt,
            cancelledAt: $cancelledAt,
        );
    }
}

Three things changed and one stayed the same.

__construct is private. No code outside the class can call new Order(...). That alone removes the worst version of the bug — the one where a caller passes a half-built order and gets back an invalid state.

place is the use-case path. It takes only what a use case has: a customer id, a cart of items, a clock. It runs domain invariants. It generates identity. It picks the starting status. Calls read Order::place($customerId, $items, $clock->now()) and you know exactly what is happening.

placeFromQuote is a sibling use case that shares the same target — a pending order — but starts from a different source. The invariants are different. The shape of the call site is different. Bundling these into one constructor would have required a third argument for "is this from a quote" and a fourth for the quote id, both nullable, both ignored half the time.

reconstitute is the persistence path. It takes everything, validates nothing, and trusts the caller. Only the ORM should be calling it. It exists because there is no other honest way to say "rebuild this object from a row without re-running creation invariants." Doctrine hydrating an order from orders should not re-check that the cart is non-empty. That check ran the day the order was placed. Re-running it on every fetch wastes CPU now and guarantees a bug the day the invariants change.

Why Doctrine needs `reconstitute`

The reconstitution problem is the one that bites teams using Doctrine ORM, Eloquent, or any other identity-map persistence layer. The ORM owns the object lifecycle on the way out of the database. It reads a row, builds an object, hands it back. If the only public constructor is place, the ORM cannot do its job. place generates a new id, sets placedAt to now, and refuses an empty cart. Three lies, told once per row.

Doctrine 3 reads private fields via reflection by default, and the default hydration mode does not call your constructor at all. It calls newInstanceWithoutConstructor() and writes fields directly. That mostly works, but it has two costs. The first is that any logic in your __construct is silently bypassed, which is fine for a private constructor that does nothing but assign, and a disaster for a public constructor that runs validation. The second is that your domain object now has two creation paths, only one of which is named, and the named one is invisible to anyone reading the class.

Adding reconstitute makes the second path explicit. The constructor becomes a private detail. Both place and reconstitute go through it for different reasons and with different expectations about validation.

Configuring Doctrine to use reconstitute requires a custom hydrator or a lifecycle approach, but the standard pattern is to point Doctrine at the private fields and let it bypass the constructor entirely, then surface reconstitute as the public, documented entry point that describes what Doctrine is doing under the hood. The factory becomes a piece of documentation that the type system enforces: anyone reading the domain class sees three named paths and understands that one of them is for the ORM.

If you want stricter control (you want the domain class to refuse direct field writes from reflection), you write a Doctrine custom hydration mode that calls Order::reconstitute(...) from the row data. That is a longer post. The named factory is the precondition for either approach.

How the call sites change

Before, every entry point looked the same and meant something different:

$order = new Order($customer, $items, OrderStatus::Pending, $now, null, null, null);

$order = new Order(
    $row['customer'],
    $row['items'],
    OrderStatus::from($row['status']),
    $row['placed_at'],
    $row['source_quote_id'],
    $row['confirmed_at'],
    $row['cancelled_at'],
);

After, the call sites read like the domain reads:

$order = Order::place($customer->id(), $cart->items(), $clock->now());

$order = Order::placeFromQuote($quote, $clock->now());

$order = Order::reconstitute(
    id: $id,
    customerId: $customerId,
    items: $items,
    status: $status,
    placedAt: $placedAt,
    sourceQuoteId: $sourceQuoteId,
    confirmedAt: $confirmedAt,
    cancelledAt: $cancelledAt,
);

The first two are short because they are the use-case paths and they take only what a use case needs. The third is long because reconstitution is supposed to look unusual. If you are typing all eight arguments by hand in a controller, the length of the call is the warning sign that you are doing something the ORM should be doing for you.

Tests get easier in a way that is hard to notice until you do it

The hidden win shows up in fixtures. A test that needs an order in a specific state used to look like this:

$order = new Order(
    new OrderId('test-1'),
    new CustomerId('c-1'),
    [new LineItem('SKU', 1, 1000)],
    OrderStatus::Confirmed,
    new DateTimeImmutable('2026-01-01'),
    null,
    new DateTimeImmutable('2026-01-02'),
    null,
);

A reader of that test has to mentally map positional arguments to fields and check which nulls mean what. With reconstitute, the test reads as a row:

$order = Order::reconstitute(
    id: new OrderId('test-1'),
    customerId: new CustomerId('c-1'),
    items: [new LineItem('SKU', 1, 1000)],
    status: OrderStatus::Confirmed,
    placedAt: new DateTimeImmutable('2026-01-01'),
    sourceQuoteId: null,
    confirmedAt: new DateTimeImmutable('2026-01-02'),
    cancelledAt: null,
);

Same fields, but the named arguments and the verb on the method tell you what kind of fixture this is. A reconstitute fixture is "an order that exists in the database in this state." A place fixture is "an order that just got placed." The test name and the factory name agree.

A small rule for choosing factory names

Pick names that match the domain verbs, not the technical operation. Order::create() is a worse name than Order::place(), because create is what the language does and place is what the customer does. Same for Order::fromArray() versus Order::reconstitute(): one names the input shape, the other names the intent.

If a factory name does not survive being read aloud to a non-engineer ("the customer places an order, the system reconstitutes an order from storage, the customer places an order from a quote"), try again. The names exist to make call sites readable years after the code is written, by people who never met the original author.

A class with three or four well-named factories and a private constructor is one of the cheapest wins in a PHP domain layer. It pays back the first time someone reads a call site and knows exactly what is happening without opening the class.

If this was useful

This is one pattern from a longer pass on what a PHP domain layer looks like when Doctrine is an adapter and use cases own the verbs. Decoupled PHP walks the named-factory pattern through the rest of the domain: value objects, transitions like confirm() and cancel(reason), the boundary between the use case and the ORM, and how to keep the same shape across Laravel and Symfony.

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

The Outbox Pattern in PHP from Scratch (No Library, 80 Lines)

Gabriel Anhaia — Tue, 19 May 2026 19:52:55 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Event-Driven Architecture Pocket Guide
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You ship an order service. The use case does two things: insert a row into orders, then publish an OrderPlaced event to RabbitMQ so the email worker, the warehouse worker, and the analytics pipeline can do their jobs.

A week later a customer support ticket lands. Order o_91f2 is in the database. The customer never got an email. Warehouse never saw it. Analytics counted it. Three downstream systems, three different answers about the same order.

You look at the code:

$this->orders->save($order);
$this->bus->publish(new OrderPlaced($order->id));

Between line one and line two, the broker connection blipped, or the PHP-FPM worker got OOM-killed, or the deploy rolled the pod mid-request. The database commit landed. The publish did not. There is no retry, no record that the publish was meant to happen, no way to reconcile.

This is the dual-write problem. It is everywhere in event-driven PHP services. The outbox pattern fixes it. You do not need a library. You need one table, one INSERT inside the same transaction, and a worker that drains the table. Total code below: about 80 lines of PHP 8.3 plus a small SQL migration.

Why the obvious fix does not work

Before the outbox, two patterns get tried. Both fail.

Pattern 1: publish then save. Publish the event first, then write to the database. If the DB write fails, you have already told the world an order exists that does not. Reads from the consumer side will look up the order and find nothing. Downstream code grows defensive nulls. This is worse than the original bug.

Pattern 2: save then publish, with a try/catch. Wrap the publish in a try/catch and log on failure. The log line is comforting. Nothing replays the failure. Next deploy, someone greps the logs for publish failed, sees 11 of them, and now has to write a one-off script to reconstruct what should have been published. The script is wrong because the event payload has drifted since then.

The root cause is that two systems (your database and your broker) cannot share a transaction. There is no atomic commit across them. You can fake one with two-phase commit, but XA on PHP-to-RabbitMQ is a route nobody walks for fun.

The outbox sidesteps the whole problem. You only write to the database. The event is a row in a table next to your domain rows, committed in the same transaction. A separate process reads the table and publishes. If the publish fails, the row stays. The worker tries again.

The table

One migration. PostgreSQL 14+ syntax. SQLite and MySQL 8 work with minor changes.

CREATE TABLE outbox_events (
    id            UUID PRIMARY KEY,
    aggregate_id  TEXT        NOT NULL,
    event_type    TEXT        NOT NULL,
    payload       JSONB       NOT NULL,
    occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    dispatched_at TIMESTAMPTZ
);

CREATE INDEX outbox_events_pending_idx
    ON outbox_events (occurred_at)
    WHERE dispatched_at IS NULL;

Six columns. dispatched_at is nullable; NULL means the event still needs to go out. The partial index keeps the scan cheap once the table grows. The worker only ever queries rows where dispatched_at IS NULL, and that set stays small as long as the worker keeps up.

payload is JSONB. The shape is whatever your domain event looks like serialized: a flat dict of primitives. Resist the urge to store the full domain object; future-you will rename fields and the old rows will not match. Treat the row as an immutable record of what was true at write time.

Writing the event inside the use case transaction

The whole point of the pattern is that the event row and the domain row commit together. That means the outbox write lives inside the same transaction as the domain write — typically inside a use case (Clean Architecture) or application service (Hexagonal).

Here is a PlaceOrder use case in PHP 8.3 with PDO:

<?php
declare(strict_types=1);

namespace App\Application\PlaceOrder;

use App\Domain\Order\Order;
use App\Domain\Order\OrderRepository;
use App\Application\Outbox\OutboxWriter;

final readonly class PlaceOrder
{
    public function __construct(
        private \PDO $db,
        private OrderRepository $orders,
        private OutboxWriter $outbox,
    ) {}

    public function handle(PlaceOrderCommand $cmd): string
    {
        $order = Order::place(
            customerId: $cmd->customerId,
            items: $cmd->items,
        );

        $this->db->beginTransaction();
        try {
            $this->orders->save($order);
            $this->outbox->write(
                aggregateId: $order->id,
                eventType: 'order.placed',
                payload: [
                    'order_id'    => $order->id,
                    'customer_id' => $order->customerId,
                    'total_cents' => $order->totalCents,
                ],
            );
            $this->db->commit();
        } catch (\Throwable $e) {
            $this->db->rollBack();
            throw $e;
        }

        return $order->id;
    }
}

Two writes, one transaction. If either fails, both roll back. Either both rows commit or neither does.

The OutboxWriter itself is twelve lines:

<?php
declare(strict_types=1);

namespace App\Application\Outbox;

use Ramsey\Uuid\Uuid;

final readonly class OutboxWriter
{
    public function __construct(private \PDO $db) {}

    public function write(
        string $aggregateId,
        string $eventType,
        array $payload,
    ): void {
        $stmt = $this->db->prepare(
            'INSERT INTO outbox_events
             (id, aggregate_id, event_type, payload)
             VALUES (:id, :agg, :type, :payload)'
        );
        $stmt->execute([
            ':id'      => Uuid::uuid7()->toString(),
            ':agg'     => $aggregateId,
            ':type'    => $eventType,
            ':payload' => json_encode($payload, JSON_THROW_ON_ERROR),
        ]);
    }
}

UUIDv7 is monotonically time-ordered, which matters later for ordered dispatch. If you are on PHP without ramsey/uuid, swap in any v7 generator or fall back to v4 plus the existing occurred_at ordering.

That is the entire write path. The use case calls into a port (OutboxWriter), the adapter is one INSERT, the rest is PHP's normal PDO transaction handling.

The worker

The worker is a long-running CLI script. It loops: pull a batch of pending events, publish each one, mark dispatched, sleep briefly, repeat.

The trick that makes it safe under concurrent workers is SELECT ... FOR UPDATE SKIP LOCKED. Postgres locks the rows the worker picked up, and any second worker that runs the same query skips them and grabs different rows. You can run three workers in parallel and they will never deliver the same event twice.

<?php
declare(strict_types=1);

namespace App\Infrastructure\Outbox;

final class OutboxDispatcher
{
    public function __construct(
        private \PDO $db,
        private EventPublisher $publisher,
        private int $batchSize = 50,
    ) {}

    public function tick(): int
    {
        $this->db->beginTransaction();

        $stmt = $this->db->prepare(
            'SELECT id, aggregate_id, event_type, payload
               FROM outbox_events
              WHERE dispatched_at IS NULL
              ORDER BY occurred_at
              LIMIT :n
              FOR UPDATE SKIP LOCKED'
        );
        $stmt->bindValue(':n', $this->batchSize, \PDO::PARAM_INT);
        $stmt->execute();
        $rows = $stmt->fetchAll(\PDO::FETCH_ASSOC);

        if ($rows === []) {
            $this->db->commit();
            return 0;
        }

        $mark = $this->db->prepare(
            'UPDATE outbox_events
                SET dispatched_at = now()
              WHERE id = :id'
        );

        foreach ($rows as $row) {
            $this->publisher->publish(
                eventType: $row['event_type'],
                aggregateId: $row['aggregate_id'],
                payload: json_decode(
                    $row['payload'], true, flags: JSON_THROW_ON_ERROR
                ),
            );
            $mark->execute([':id' => $row['id']]);
        }

        $this->db->commit();
        return count($rows);
    }
}

A CLI entrypoint runs tick() in a loop:

$dispatcher = $container->get(OutboxDispatcher::class);

while (true) {
    $n = $dispatcher->tick();
    if ($n === 0) {
        usleep(200_000);
    }
}

Run it as a systemd service, a Kubernetes deployment, a Supervisor program — whatever your stack uses for long-lived PHP processes. Three workers on three pods, no coordination, all picking up different rows because of SKIP LOCKED.

Delivery semantics

The pattern gives you at-least-once delivery. The publisher can crash after publishing but before marking dispatched. On restart, the worker will pick the row up again and republish. Consumers must be idempotent — keep a processed_event_ids table or check by event UUID before acting.

If you need ordering per aggregate (order.placed before order.paid for the same order), the ORDER BY occurred_at already gives it to you within a single worker. Across workers, you have two choices: shard by aggregate_id (hash modulo worker count) so one aggregate's events always land on one worker, or accept that downstream consumers re-order using the event timestamp. The shard route is more work; the timestamp route is usually fine because consumers grouped by aggregate also tend to be the ones holding state per aggregate.

If you really need exactly-once, the outbox alone will not give it to you. Exactly-once is a downstream-consumer concern, solved by the consumer's idempotency key. The outbox publishes at least once. The consumer must dedupe. Combined, you get effectively-once delivery.

Operational notes after the table grows

Two things will bite you in month three.

Table bloat. outbox_events grows forever if nothing prunes it. Add a daily job:

DELETE FROM outbox_events
 WHERE dispatched_at IS NOT NULL
   AND dispatched_at < now() - INTERVAL '7 days';

Seven days is generous; pick whatever your audit needs require. The partial index on dispatched_at IS NULL already keeps the worker query fast, so the bloat only hurts disk and full-table scans. Pruning fixes both.

Stuck rows. If the publisher repeatedly fails on one event (malformed payload, broker-side schema rejection), the row sits there and the worker keeps retrying it forever, blocking newer events for the same aggregate. Add a retry counter and a dead-letter outcome:

ALTER TABLE outbox_events
    ADD COLUMN attempts INT NOT NULL DEFAULT 0,
    ADD COLUMN last_error TEXT;

In the worker, wrap the publisher->publish call in a try/catch: on success, run the existing UPDATE ... SET dispatched_at = now(); on failure, run UPDATE outbox_events SET attempts = attempts + 1, last_error = :msg WHERE id = :id and continue. Then change the SELECT to add AND attempts < 10 so poisoned rows fall out of the pending set automatically (point a dead-letter view at attempts >= 10 for on-call). Without it, one bad row will page you at 3am.

What you have built

Around 80 lines of PHP plus a small SQL migration, and you have:

Atomic write of the domain row and its event.
Concurrent workers, no coordination, courtesy of FOR UPDATE SKIP LOCKED.
At-least-once delivery, retry-safe.
A real durable record of every event the service has emitted.

No Symfony Messenger transport. No Laravel queue driver. No Kafka Connect Debezium pipeline. Those tools earn their weight once you outgrow this. For the first year of a service, this is what they all reduce to underneath.

The hard part isn't the broker or the framework. It's the boundary between your domain and the broker, and the question of what commits with what. The outbox draws that boundary with one table.

If this was useful

This is one chapter of how Decoupled PHP treats async adapters — events get committed alongside the domain row, the worker is an outbound adapter behind a port, and the framework (Laravel or Symfony) shows up only at the edges. If you want to see the full layout — the port for EventPublisher, the dead-letter path, the testing strategy for the dispatcher without a real broker — the book walks the whole shape end to end.

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

Three Layers vs Four Layers: When the Application Layer Earns Its Keep

Gabriel Anhaia — Tue, 19 May 2026 19:52:34 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: System Design Pocket Guide: Fundamentals
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You open a fresh Laravel project. The controller calls a repository. The repository hydrates an entity. The entity has a method or two. Three layers, total. The feature ships on Tuesday and nobody on the team is unhappy.

Six months later the same controller has a sibling: a CLI command that runs the same flow at 3 a.m. Then a queue worker picks up the same flow from a webhook. The controller, the command, and the worker all do the same five things (load the customer, validate, compute, save, dispatch), and they all do them slightly differently. The tests for each entry point repeat the same setup. A small change to the order rules touches three files in three different parts of the codebase.

That's the moment the missing fourth layer starts charging interest.

The two shapes, side by side

The three-layer shape is the Laravel/Symfony default that ships in every starter:

HTTP Controller ──▶ Repository ──▶ Entity (DB row)

The four-layer shape inserts a Use Case between the controller and the repository:

HTTP Controller ──▶ Use Case ──▶ Repository ──▶ Entity
CLI Command     ──▶ Use Case ──▶ Repository ──▶ Entity
Queue Worker    ──▶ Use Case ──▶ Repository ──▶ Entity

The Use Case (Clean Architecture vocabulary; "application service" in DDD-flavored books; "interactor" in Robert C. Martin's original) is one class with one public method that owns the business operation. The controller becomes a translator: HTTP in, DTO out. The repository goes back to being a thin persistence wrapper.

The shapes disagree about who is allowed to call what, not where the code goes. In a three-layer service the controller is the orchestrator. In a four-layer service the controller is an adapter, and the use case is the orchestrator.

Three layers in PHP, no apologies

For a service with one HTTP entry point and a straight read/write per request, three layers is the right answer. Here is what it looks like with declare(strict_types=1) and a recent Laravel container.

<?php
declare(strict_types=1);

final class OrderController
{
    public function __construct(
        private OrderRepository $orders,
        private Clock $clock,
    ) {}

    public function store(StoreOrderRequest $req): JsonResponse
    {
        $items = array_map(
            static fn (array $i) => new Item(
                sku: $i['sku'],
                quantity: $i['quantity'],
                priceCents: $i['price_cents'],
            ),
            $req->validated()['items'],
        );

        $order = new Order(
            id: Order::newId(),
            customerId: $req->customerId(),
            items: $items,
            totalCents: Order::totalFor($items),
            createdAt: $this->clock->now(),
        );

        $this->orders->save($order);

        return new JsonResponse($order, 201);
    }
}

That is the whole pipeline. The controller hydrates from the request, calls a domain helper for the math, asks the repository to save. No orchestration class in the middle, because nothing in the middle is being shared.

This shape is honest when:

There is exactly one entry point (HTTP, or only CLI, or only worker).
The operation is one transactional unit: a single INSERT or a single UPDATE, no follow-on side effects that need to succeed together.
The validation rules belong to the input shape (StoreOrderRequest checks them), not to a cross-cutting business invariant.

Adding a use case here would mean a class named CreateOrderUseCase that takes the same arguments, calls the same repository, returns the same DTO, and forces every test to mock one more boundary. The ceremony costs more than it returns. Skip it.

When the third entry point arrives

The story changes when a second caller shows up. A nightly cron now needs to backfill orders from a partner CSV. The 3 a.m. command can't go through HTTP — there is no request, no StoreOrderRequest, no JsonResponse. The original instinct is to extract a private method:

private function createOrder(string $customerId, array $items): Order
{
    // copy-pasted body from the controller
}

And then call that from a console command. Six months later a third caller (a Stripe webhook worker) does the same dance. Now the "private method" lives somewhere awkward. It is either still on the controller (which the worker has to instantiate), or on a base class that everything extends, or on a "service" with a name like OrderService. That class became a junk drawer for anything the team couldn't place.

The use case is the named, deliberate version of the same extraction. One class, one method, the orchestration of the operation, decoupled from how it was triggered.

<?php
declare(strict_types=1);

final readonly class CreateOrder
{
    public function __construct(
        private OrderRepository $orders,
        private CustomerRepository $customers,
        private EventDispatcher $events,
        private Clock $clock,
    ) {}

    public function execute(CreateOrderInput $in): Order
    {
        $customer = $this->customers->byId($in->customerId)
            ?? throw new CustomerNotFound($in->customerId);

        if (!$customer->canPurchase()) {
            throw new CustomerBlocked($in->customerId);
        }

        $order = new Order(
            id: Order::newId(),
            customerId: $customer->id,
            items: $in->items,
            totalCents: Order::totalFor($in->items),
            createdAt: $this->clock->now(),
        );

        $this->orders->save($order);
        $this->events->dispatch(new OrderCreated($order->id));

        return $order;
    }
}

CreateOrderInput is a plain DTO with public readonly fields, no validation logic, no framework binding. The HTTP controller builds one from StoreOrderRequest. The CLI builds one from CSV rows. The webhook worker builds one from the Stripe payload. Three entry points, one operation, one place to change the rules.

The controller shrinks to a translator:

public function store(StoreOrderRequest $req, CreateOrder $createOrder): JsonResponse
{
    $input = CreateOrderInput::fromRequest($req);
    $order = $createOrder->execute($input);
    return new JsonResponse($order, 201);
}

The CLI is the same shape with a different translator:

protected function handle(CreateOrder $createOrder): int
{
    foreach ($this->readCsv($this->argument('file')) as $row) {
        $createOrder->execute(CreateOrderInput::fromCsvRow($row));
    }
    return self::SUCCESS;
}

The worker, the same. Each adapter owns its transport. The business operation lives in one place.

What you actually gain (and what you don't)

The four-layer shape is not free. You add one class per operation, one DTO per operation, one set of unit tests for the use case, and a small amount of wiring in the container. For a 5-endpoint CRUD admin, that overhead is real and unhelpful.

The payback shows up when one of these is true:

Multiple entry points hit the same operation. HTTP + CLI + queue worker is the canonical trio. Two of the three is enough to justify the extraction. One is not.

The operation spans multiple writes that must succeed together. Save the order, dispatch the event, decrement the inventory, log the audit row. A controller doing all four with DB::transaction(function () { ... }) works until the second entry point arrives. At that point the transaction boundary moves with the operation, not with the request. The use case owns the boundary.

public function execute(CreateOrderInput $in): Order
{
    return $this->tx->run(function () use ($in): Order {
        $order = $this->build($in);
        $this->orders->save($order);
        $this->inventory->reserve($order);
        $this->audit->record($order);
        $this->events->dispatch(new OrderCreated($order->id));
        return $order;
    });
}

The transaction belongs to the operation's contract. The controller stays out of it.

The operation has a name the product owner uses. "Create order", "Approve refund", "Suspend account", "Resume subscription". When the operation has a name in the product spec, giving it a class with that name pays off in code review and onboarding. New engineers grep for the verb and find the file.

The rules will outlive the framework. When you can imagine the same operation moving from Laravel 11 to Symfony 7, or from a monolith to a queue worker in its own deployable, the use case is the unit you carry. Controllers and repositories get rewritten per framework.

You do not gain testability automatically. You can test a three-layer service well with a repository fake. You can test a four-layer service badly with too many mocks. The win is structural. Once the use case is its own class, a test instantiates it with fake collaborators and runs without the framework container.

The decision table

Signal	Three layers is fine	Four layers earns its keep
Entry points to the operation	One	Two or more
Writes per operation	One	Multiple, must commit together
Operation name in the spec	"Endpoint X"	A verb the product owner says aloud
Side effects (events, audits, external calls)	None or one	Two or more, ordered
Validation surface	Input shape only	Cross-cutting business rules
Expected lifespan	Months	Years across framework upgrades
Team size touching this code	One or two devs	A rotation of devs over time

Two or more rows pointing right? Add the use case. All rows pointing left? Don't.

A middle path: extract on the second caller, not the first

The four-layer shape doesn't have to be a day-one decision. The honest pattern in PHP teams that ship well:

Ship the three-layer version. Controller calls repository calls entity. Done in an afternoon.
When the second caller arrives, extract the use case. Move the orchestration out of the controller into a named class. The controller becomes a translator; the new caller gets the same translator pattern.
When the third caller arrives, the cost is zero. There is already a use case to call.

The cost of waiting is one refactor at step 2. The cost of going four-layer on day one for a service that never gets a second caller is permanent overhead. The trade is real.

The thing to watch for is the version of step 1 that becomes load-bearing. If the controller's private method has been copy-pasted into a console command and the team is now editing both copies whenever the rules change, you skipped step 2. Catch yourself.

Where the application layer ends and the domain layer begins

A common confusion: people read about "the application layer" and start putting business rules in the use case. That is a wrong turn. The use case orchestrates. The entity (or a domain service when the rule doesn't fit on an entity) decides.

final readonly class Order
{
    public static function totalFor(array $items): int
    {
        return array_reduce(
            $items,
            static fn (int $sum, Item $i) => $sum + $i->priceCents * $i->quantity,
            0,
        );
    }
}

totalFor is a domain rule. It lives on Order, not in CreateOrder. The use case calls it. If you find your use case computing totals, validating SKUs, or applying discount logic, those rules want to move down a layer. The use case stays a thin sequencer: load, decide via the domain, save, dispatch.

That separation is what lets the four-layer shape survive. The day you migrate from Laravel to Symfony, the domain and the use cases come with you. The controllers and the repositories are rewritten. If business rules were spread across the controller, the use case, and the entity, the migration would be a year of work. Concentrated in the domain, it is a weekend.

Verdict

Add the fourth layer the moment a second entry point appears, or the moment the operation grows a second write that must commit with the first. Name the class after the verb the product owner uses. Keep the orchestration in the use case and the rules in the domain. Picking the wrong shape for the scope costs you either ceremony you didn't need or refactors you should have avoided.

If this was useful

The four-layer pattern is the spine of Decoupled PHP — use cases, ports, adapters, and the migration playbook for taking a framework-coupled Laravel or Symfony service to a shape that survives the next framework upgrade. The book walks the same operation from a one-entry-point CRUD up through HTTP + CLI + queue with transactional orchestration, in production-grade PHP 8.3.

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

Schema Migrations vs Aggregate Evolution: Two Different Problems

Gabriel Anhaia — Tue, 19 May 2026 19:52:07 +0000

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

You open a pull request titled "Add partially_refunded state to Order". The diff has one Doctrine migration adding an enum value to a Postgres column, one change to a PHP enum, and three new branches inside Order::canShip(). CI is green. The reviewer hits approve. You merge.

Two days later support pings: orders that were already in refunded are now showing up as unknown in the dashboard, and a queue worker is throwing on an old serialized order pulled out of Redis. The migration ran. The deploy went out. The data is still wrong.

You ran a schema migration. The change you actually shipped was an aggregate evolution. They have different invariants, rollback shapes, and blast radii. Treating them as one thing is how you end up there at 2am.

What each one is

A schema migration moves the database from one shape to another. ALTER TABLE orders ADD COLUMN currency CHAR(3) NOT NULL DEFAULT 'EUR'. CREATE INDEX. DROP COLUMN. The unit of change is the relation. The tooling is well understood: Doctrine Migrations, Phinx, raw SQL files, php artisan migrate. The success criterion is the schema now matches what the code expects.

An aggregate evolution changes the meaning of a domain object. Order used to be pending | confirmed | shipped | refunded. Now there is a fifth state — partially_refunded — and the rules for what transitions into it, what it allows, and how the rest of the system reads it are all new. The unit of change is the aggregate's behavior contract. The tooling is your codebase, your tests, and your in-flight data. The success criterion is every existing Order can still be loaded, mutated, and reasoned about — including the ones that were serialized before the change existed.

A schema migration touches storage. An aggregate evolution touches semantics. Most non-trivial changes are both, which is the trap.

The pure schema migration

Here is a clean one. You want to track currency on every Order. The domain already has a Money value object; the column was missing.

-- migrations/Version20260519000001.php (up)
ALTER TABLE orders
    ADD COLUMN currency CHAR(3) NOT NULL DEFAULT 'EUR';

CREATE INDEX idx_orders_currency ON orders (currency);

<?php

declare(strict_types=1);

namespace App\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class Version20260519000001 extends AbstractMigration
{
    public function up(Schema $schema): void
    {
        $this->addSql(
            'ALTER TABLE orders ADD COLUMN currency '
            . "CHAR(3) NOT NULL DEFAULT 'EUR'"
        );
        $this->addSql(
            'CREATE INDEX idx_orders_currency '
            . 'ON orders (currency)'
        );
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP INDEX idx_orders_currency');
        $this->addSql('ALTER TABLE orders DROP COLUMN currency');
    }
}

The properties of this change:

Idempotent at the schema level. Run it twice and the second run fails loudly. Doctrine's migrations table tracks that.
Reversible. The down() is a real inverse. DROP COLUMN gets you back.
Default-safe. Every existing row gets 'EUR'. Nothing in the application breaks the moment after the migration finishes, because the schema has a sensible value for everyone.
Blast radius: the database. A bad migration locks a table. The fix is to roll it back. The data is intact.

You can ship this migration ahead of the code that reads currency, and ship the code reading currency ahead of any code that writes it. The classic expand-contract play. Your aggregate didn't move.

The aggregate evolution that looks like a migration

Now the bad one. Product comes back and says: "We need a partially_refunded state. An Order can be partially refunded after it ships if any line item is returned. A partially refunded order is still shippable for the unreturned items if they haven't gone out yet."

You write the migration that looks the same as before:

ALTER TYPE order_status ADD VALUE 'partially_refunded';

You change the enum:

<?php

declare(strict_types=1);

namespace App\Domain\Order;

enum OrderStatus: string
{
    case Pending = 'pending';
    case Confirmed = 'confirmed';
    case Shipped = 'shipped';
    case Refunded = 'refunded';
    case PartiallyRefunded = 'partially_refunded';
}

You patch canShip(). CI is green. You ship.

What you missed:

Old serialized aggregates. Queue payloads in Redis, snapshots in an event store, JSON columns in a reporting table — anything serialized before this change has only the four-state vocabulary. Loading them is fine. Comparing their status against the new five-state domain is where it breaks.
Existing rows that should be partially_refunded. There are orders in production right now where line items were returned in a separate flow. Their status column says refunded or shipped because that's all the schema allowed. The new state is meaningless until you backfill them.
Code that reads the status enum. Every match ($order->status) in the codebase compiles fine until it hits a PartiallyRefunded value at runtime and falls through to a default arm that throws or — worse — silently returns false.
Read-side projections. Dashboards, exports, the admin UI's filter dropdown, the analytics warehouse — they all have their own copy of the status vocabulary. None of them got migrated by your ALTER TYPE.

The schema change took one line. The evolution is everything else.

The evolution playbook in PHP

The pattern that makes this safe has three moves: a domain change that accepts the old shape, a backfill that creates the new shape, and a read-fallback that translates anything missed.

1. Domain accepts both shapes

The aggregate's constructor and reconstitution path must not reject historic data. The new state is added; the old states still load.

<?php

declare(strict_types=1);

namespace App\Domain\Order;

use App\Domain\Money\Money;

final class Order
{
    public function __construct(
        public readonly OrderId $id,
        public readonly CustomerId $customerId,
        private OrderStatus $status,
        private Money $total,
        private Money $refundedAmount,
    ) {
    }

    public static function fromRow(array $row): self
    {
        $status = OrderStatus::tryFrom($row['status'])
            ?? OrderStatus::Pending;

        $refunded = isset($row['refunded_amount_cents'])
            ? Money::ofMinor(
                (int) $row['refunded_amount_cents'],
                $row['currency'] ?? 'EUR',
            )
            : Money::zero($row['currency'] ?? 'EUR');

        return new self(
            id: OrderId::fromString($row['id']),
            customerId: CustomerId::fromString($row['customer_id']),
            status: $status,
            total: Money::ofMinor(
                (int) $row['total_cents'],
                $row['currency'] ?? 'EUR',
            ),
            refundedAmount: $refunded,
        );
    }

    public function canShip(): bool
    {
        return match ($this->status) {
            OrderStatus::Confirmed,
            OrderStatus::PartiallyRefunded => true,
            OrderStatus::Pending,
            OrderStatus::Shipped,
            OrderStatus::Refunded => false,
        };
    }

    public function applyRefund(Money $amount): void
    {
        $newRefunded = $this->refundedAmount->plus($amount);

        if ($newRefunded->isGreaterThan($this->total)) {
            throw new \DomainException(
                'Refund exceeds order total',
            );
        }

        $this->refundedAmount = $newRefunded;
        $this->status = $newRefunded->equals($this->total)
            ? OrderStatus::Refunded
            : OrderStatus::PartiallyRefunded;
    }
}

fromRow does not assume the column exists. tryFrom returns null for unknown values and the caller falls back to a default. applyRefund enforces the new invariant (partial means less than total, full means equal) and writes the correct status. Every match on OrderStatus covers all cases, so PHPStan or Psalm flags any arm you forgot to add, and an uncovered arm throws UnhandledMatchError the first time your tests hit it.

2. Backfill that creates the new shape

You need a script that walks existing rows and assigns the new state where it applies. This runs after the schema migration and before the read-fallback gets retired.

<?php

declare(strict_types=1);

namespace App\Migrations\Backfill;

use Doctrine\DBAL\Connection;

final class PartiallyRefundedBackfill
{
    public function __construct(private Connection $db)
    {
    }

    public function run(int $batchSize = 500): int
    {
        $touched = 0;

        $rows = $this->db->fetchAllAssociative(
            'SELECT id, total_cents, refunded_amount_cents
             FROM orders
             WHERE refunded_amount_cents > 0
               AND refunded_amount_cents < total_cents
               AND status <> ?',
            ['partially_refunded'],
        );

        foreach (array_chunk($rows, $batchSize) as $chunk) {
            $ids = array_column($chunk, 'id');

            $this->db->executeStatement(
                'UPDATE orders
                 SET status = ?
                 WHERE id IN (?)',
                ['partially_refunded', $ids],
                [\PDO::PARAM_STR, Connection::PARAM_STR_ARRAY],
            );

            $touched += count($chunk);
        }

        return $touched;
    }
}

This is not a schema migration. It does not belong in migrations/. It is a one-shot domain backfill, run as a command, logged, idempotent (re-running it touches the same rows and produces the same answer), and audited. The output goes to a ticket.

The difference matters because schema migrations are part of the deploy pipeline; backfills are part of the release plan. A schema migration runs in seconds and blocks the deploy. A backfill runs in minutes or hours, in batches, and the deploy goes out without waiting for it.

3. Read-fallback for anything you missed

Some rows escape the backfill. Maybe they were created during the backfill window. Maybe the upstream system that writes refunds has a separate code path you forgot. Maybe an offline replica caught up after the script ran.

The repository handles those cases by reconstructing the correct state on read:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence\Doctrine;

use App\Domain\Order\Order;
use App\Domain\Order\OrderId;
use App\Domain\Order\OrderRepository;
use App\Domain\Order\OrderStatus;
use Doctrine\DBAL\Connection;

final class DoctrineOrderRepository implements OrderRepository
{
    public function __construct(private Connection $db)
    {
    }

    public function get(OrderId $id): Order
    {
        $row = $this->db->fetchAssociative(
            'SELECT * FROM orders WHERE id = :id',
            ['id' => $id->toString()],
        );

        if ($row === false) {
            throw new OrderNotFound($id);
        }

        $row = $this->reconcileStatus($row);

        return Order::fromRow($row);
    }

    private function reconcileStatus(array $row): array
    {
        $refunded = (int) ($row['refunded_amount_cents'] ?? 0);
        $total = (int) $row['total_cents'];

        if ($refunded > 0 && $refunded < $total) {
            $row['status'] = OrderStatus::PartiallyRefunded->value;
        }

        return $row;
    }
}

The fallback is tactical. It exists for the weeks between the deploy and a clean backfill report. Once the backfill log shows zero rows touched on a fresh run, the fallback gets ripped out in a small PR that also removes a TODO.

Failure modes, side by side

Aspect	Schema migration	Aggregate evolution
Unit of change	A table or column	A domain object's contract
Tool	Doctrine Migrations, Phinx, raw SQL	Code + backfill + tests
Reversible?	Yes, with a real `down()`	Rarely — you cannot un-think a state
In-flight data	DEFAULT clause handles it	Needs explicit backfill or read-fallback
Blast radius	The DB	Every consumer of the aggregate
Pre-flight check	Dry-run on staging schema	Type checker + property tests on real shapes
Rollback if wrong	`down()` migration	Feature flag the new state; backfill the inverse

The shape of the rollback is the giveaway. When a schema migration is wrong, you run a migration to undo it. When an aggregate evolution is wrong, there is no migration that fixes it. You ship a code change that translates the broken intermediate state back to something sane, then backfill again.

Where this lands in a hex codebase

Push schema migrations into the adapter layer. They are an infrastructure concern; the domain doesn't know they exist. Doctrine migrations live next to the repository, get versioned with the deploy, and never import a domain type.

Aggregate evolutions live in the domain. The enum, the invariants, the new methods, the totality of the match arms — all of that is domain code. The repository's job is to translate persistence rows into a valid aggregate; the backfill's job is to make sure persistence rows can actually become valid aggregates without the repository having to guess.

When you separate them this way, the PR diff tells you what you actually shipped. A diff with only migrations/ changes? Schema only. A diff with migrations/, src/Domain/, a bin/backfill-*.php, and a reconcileStatus block? You are shipping an evolution and you owe the playbook.

The mistake at the top of this post — merging an evolution as if it were a migration — happens because the diff looked small. Three branches in canShip, one new enum case, one DDL. The expensive parts are the parts that aren't in the diff: the in-flight queue payloads, the read-side projections, the existing rows that match the new state's definition but are stored under the old vocabulary. Knowing which kind of change you are shipping is what makes you remember to look for them.

If this was useful

Most production bugs in framework-coupled PHP apps are the same shape as the one above: a change that looks like infrastructure but is actually domain. Decoupled PHP walks the full pattern — keeping the aggregate's behavior contract in the domain, treating Doctrine migrations as adapter detail, and giving evolutions a real playbook instead of a hope. If you spend time on long-lived PHP services, the chapter on transactions and the one on migrating a legacy Laravel service are where the book pays for itself.

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

Multi-Tenant Routing in Hexagonal PHP

Gabriel Anhaia — Tue, 19 May 2026 19:51:48 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: System Design Pocket Guide: Fundamentals
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You know the bug before you read the postmortem. Acme Corp opens a ticket: their dashboard is showing rows for Globex. The Globex account manager opens the same screen and sees Acme's invoices. Somebody on the team forgot a where tenant_id = ? clause in one repository method. It shipped. It passed code review. A team gets paged late at night, on a call with two customers explaining what happened.

That bug is a class. Not a typo. What happens when the tenant identifier gets treated as a parameter you remember to pass, instead of a property of the seam between the application and its data.

Hexagonal architecture gives you somewhere to put the fix. TenantId is a domain concept. Every aggregate belongs to exactly one tenant, and the business rule "no read or write ever crosses tenants" is a domain invariant. The mechanics of how you enforce it (separate schemas, a row filter, separate connection pools) belong outside the domain. Once the seam is right, the type system and the adapter refuse the bad query before it runs.

What belongs in the domain

The domain owns one thing about multi-tenancy: the fact that a TenantId exists, and the fact that every aggregate root carries one. The domain knows nothing about how you route queries, which connection a tenant lives on, or whether you use schema-per-tenant or shared-tables-with-filter.

<?php
declare(strict_types=1);

namespace App\Domain\Tenant;

final readonly class TenantId
{
    public function __construct(public string $value)
    {
        if (!preg_match('/^[a-z0-9-]{3,64}$/', $value)) {
            throw new \InvalidArgumentException(
                "invalid tenant id: {$value}"
            );
        }
    }

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

That's the whole domain side of multi-tenancy. A value object. No service locator, no static call to fetch "the current tenant", no Eloquent global scope.

An Order aggregate carries one:

<?php
declare(strict_types=1);

namespace App\Domain\Order;

use App\Domain\Tenant\TenantId;

final readonly class Order
{
    public function __construct(
        public OrderId $id,
        public TenantId $tenantId,
        public CustomerId $customerId,
        public int $totalCents,
    ) {}
}

The constructor forces TenantId. There is no way to build an Order that doesn't know which tenant it belongs to. A developer cannot accidentally persist a tenantless order, because the type won't let them.

What belongs outside

The interesting part is the adapter. There are three common shapes for tenant-aware storage in PHP. The hexagonal answer is the same for all three: pick one, hide it behind a port, the domain doesn't care.

Strategy	What it does	When to reach for it
Schema-per-tenant	Each tenant has its own `tenant_acme.orders` table	Strong isolation requirements, ≤ a few hundred tenants, comfort with migrations across many schemas
Row filter	Shared `orders` table, every query carries `WHERE tenant_id = ?`	Many small tenants, you want one place to operate, the row count per table is fine
Connection-pool routing	Each tenant maps to a physical DB host	Compliance or noisy-neighbor isolation, willing to operate N databases

The repository port is identical for all three. It does not mention TenantId because the adapter already knows it.

<?php
declare(strict_types=1);

namespace App\Domain\Order;

interface OrderRepository
{
    public function save(Order $order): void;
    public function findById(OrderId $id): ?Order;
    public function listForCustomer(CustomerId $id): array;
}

The domain reads as if there were one tenant. The adapter does the routing.

The seam: a tenant-aware connection

The piece that turns "I remembered to filter by tenant" into "I cannot forget to filter by tenant" is a connection wrapper that closes over the current TenantId and refuses to issue a query that doesn't honor it. Every adapter goes through this wrapper. There is no other path to the database from inside the application.

<?php
declare(strict_types=1);

namespace App\Infrastructure\Persistence;

use App\Domain\Tenant\TenantId;
use PDO;
use PDOStatement;

final class TenantAwareConnection
{
    public function __construct(
        private readonly PDO $pdo,
        private readonly TenantId $tenantId,
    ) {}

    public function tenantId(): TenantId
    {
        return $this->tenantId;
    }

    public function prepare(string $sql): PDOStatement
    {
        $this->assertTenantClause($sql);
        return $this->pdo->prepare($sql);
    }

    public function execute(string $sql, array $params): PDOStatement
    {
        $this->assertTenantClause($sql);
        $params['tenant_id'] = $this->tenantId->value;
        $stmt = $this->pdo->prepare($sql);
        $stmt->execute($params);
        return $stmt;
    }

    private function assertTenantClause(string $sql): void
    {
        $normalized = strtolower($sql);
        $isWrite = str_starts_with(ltrim($normalized), 'insert')
            || str_starts_with(ltrim($normalized), 'update')
            || str_starts_with(ltrim($normalized), 'delete');

        $hasTenant = str_contains($normalized, ':tenant_id')
            || str_contains($normalized, 'tenant_id =');

        if (!$hasTenant) {
            throw new \LogicException(
                'query rejected: no tenant_id binding. '
                . 'every query through TenantAwareConnection '
                . 'must reference :tenant_id'
            );
        }

        if ($isWrite && !str_contains($normalized, ':tenant_id')) {
            throw new \LogicException(
                'write rejected: tenant_id must be bound, not literal'
            );
        }
    }
}

The wrapper carries the tenant, rejects any SQL that doesn't bind :tenant_id, and auto-binds the parameter so the repository can't pass the wrong one. A repository method that forgets the filter throws on the prepare call, and the first time you run the test in development, it throws. There is no path to production for that bug.

The string check is a guardrail. The real guarantee is the adapter underneath this wrapper, the row filter or schema selector, which never sees a query without the tenant. The string check is what makes the omission loud in dev so it never reaches the row-filter layer in the first place.

The middleware: where TenantId enters the world

TenantId doesn't appear from thin air. It comes from the request — a subdomain, a header, a JWT claim, a session. That extraction is an inbound adapter concern. The middleware reads it, validates it, and pushes it into a request-scoped container before any controller or use case runs.

<?php
declare(strict_types=1);

namespace App\Infrastructure\Http;

use App\Domain\Tenant\TenantId;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

final class TenantContextMiddleware implements MiddlewareInterface
{
    public function __construct(
        private readonly TenantResolver $resolver,
        private readonly TenantContext $context,
    ) {}

    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler,
    ): ResponseInterface {
        $tenantId = $this->resolver->resolve($request);

        if ($tenantId === null) {
            return new JsonResponse(
                ['error' => 'tenant not resolved'],
                401,
            );
        }

        $this->context->bind($tenantId);

        try {
            return $handler->handle(
                $request->withAttribute('tenant_id', $tenantId),
            );
        } finally {
            $this->context->clear();
        }
    }
}

The TenantContext is request-scoped: one instance per HTTP request, bound at the start and cleared at the end. In Symfony you register it as a request-scoped service and inject; in Laravel you bind it as a scoped singleton; in a long-running worker (Roadrunner, FrankenPHP, Swoole) you reset it on each job.

<?php
declare(strict_types=1);

namespace App\Infrastructure\Tenant;

use App\Domain\Tenant\TenantId;

final class TenantContext
{
    private ?TenantId $current = null;

    public function bind(TenantId $tenantId): void
    {
        $this->current = $tenantId;
    }

    public function current(): TenantId
    {
        if ($this->current === null) {
            throw new \LogicException(
                'no tenant bound — every entry point '
                . 'must run TenantContextMiddleware first'
            );
        }
        return $this->current;
    }

    public function clear(): void
    {
        $this->current = null;
    }
}

The factory for TenantAwareConnection resolves the TenantId from this context at injection time:

<?php
declare(strict_types=1);

namespace App\Infrastructure\Persistence;

use App\Infrastructure\Tenant\TenantContext;
use PDO;

final class TenantAwareConnectionFactory
{
    public function __construct(
        private readonly PDO $pdo,
        private readonly TenantContext $context,
    ) {}

    public function forCurrentTenant(): TenantAwareConnection
    {
        return new TenantAwareConnection(
            $this->pdo,
            $this->context->current(),
        );
    }
}

If a worker, console command, or scheduled job calls into a use case without first binding a TenantId, the factory throws on construction. Every entry point has to declare which tenant it is operating as.

The repository: tenant-scoped by construction

The repository receives a TenantAwareConnection that is already scoped to one tenant. It never reads from TenantContext. It never accepts a TenantId parameter. Its only API is "operate on this tenant's data, whichever tenant that is".

<?php
declare(strict_types=1);

namespace App\Infrastructure\Persistence;

use App\Domain\Order\Order;
use App\Domain\Order\OrderId;
use App\Domain\Order\OrderRepository;
use App\Domain\Order\CustomerId;
use App\Domain\Tenant\TenantId;

final class PdoOrderRepository implements OrderRepository
{
    public function __construct(
        private readonly TenantAwareConnection $conn,
    ) {}

    public function save(Order $order): void
    {
        $this->assertSameTenant($order->tenantId);

        $this->conn->execute(
            'insert into orders (id, tenant_id, customer_id, total_cents)
             values (:id, :tenant_id, :customer_id, :total_cents)
             on conflict (id) do update
                set total_cents = excluded.total_cents
                where orders.tenant_id = :tenant_id',
            [
                'id' => $order->id->value,
                'customer_id' => $order->customerId->value,
                'total_cents' => $order->totalCents,
            ],
        );
    }

    public function findById(OrderId $id): ?Order
    {
        $stmt = $this->conn->execute(
            'select id, tenant_id, customer_id, total_cents
             from orders
             where id = :id and tenant_id = :tenant_id',
            ['id' => $id->value],
        );

        $row = $stmt->fetch(\PDO::FETCH_ASSOC);
        return $row ? $this->hydrate($row) : null;
    }

    public function listForCustomer(CustomerId $id): array
    {
        $stmt = $this->conn->execute(
            'select id, tenant_id, customer_id, total_cents
             from orders
             where customer_id = :customer_id
               and tenant_id = :tenant_id
             order by id',
            ['customer_id' => $id->value],
        );

        return array_map(
            $this->hydrate(...),
            $stmt->fetchAll(\PDO::FETCH_ASSOC),
        );
    }

    private function assertSameTenant(TenantId $orderTenant): void
    {
        if (!$orderTenant->equals($this->conn->tenantId())) {
            throw new CrossTenantWriteException(
                "order belongs to {$orderTenant->value}, "
                . "connection is scoped to "
                . "{$this->conn->tenantId()->value}",
            );
        }
    }

    private function hydrate(array $row): Order
    {
        return new Order(
            new OrderId($row['id']),
            new TenantId($row['tenant_id']),
            new CustomerId($row['customer_id']),
            (int) $row['total_cents'],
        );
    }
}

The upsert's where orders.tenant_id = :tenant_id clause and the assertSameTenant check both block the same bug from two angles. The upsert can't overwrite a row belonging to another tenant even if a malicious or buggy caller passes a duplicate ID. The assertSameTenant check rejects an Order whose tenantId doesn't match the connection's tenantId. That catches the "use case loaded an order, mutated it, then tried to save it through a different tenant's connection" bug.

The test that proves the seam holds

A code review can miss a cross-tenant read. A test cannot. The test you want is the one that tries to do the wrong thing and asserts that it fails.

<?php
declare(strict_types=1);

namespace Tests\Integration\Persistence;

use App\Domain\Order\CustomerId;
use App\Domain\Order\Order;
use App\Domain\Order\OrderId;
use App\Domain\Tenant\TenantId;
use App\Infrastructure\Persistence\CrossTenantWriteException;
use App\Infrastructure\Persistence\PdoOrderRepository;
use App\Infrastructure\Persistence\TenantAwareConnection;
use PDO;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\TestCase;

final class CrossTenantIsolationTest extends TestCase
{
    private PDO $pdo;

    protected function setUp(): void
    {
        $this->pdo = new PDO('sqlite::memory:');
        $this->pdo->setAttribute(
            PDO::ATTR_ERRMODE,
            PDO::ERRMODE_EXCEPTION,
        );
        $this->pdo->exec(
            'create table orders (
                id text not null,
                tenant_id text not null,
                customer_id text not null,
                total_cents integer not null,
                primary key (id, tenant_id)
            )',
        );
    }

    #[Test]
    public function read_for_one_tenant_does_not_see_another_tenants_row(): void
    {
        $acme = new TenantId('acme');
        $globex = new TenantId('globex');

        $acmeRepo = new PdoOrderRepository(
            new TenantAwareConnection($this->pdo, $acme),
        );
        $globexRepo = new PdoOrderRepository(
            new TenantAwareConnection($this->pdo, $globex),
        );

        $acmeRepo->save(new Order(
            new OrderId('order-1'),
            $acme,
            new CustomerId('cust-1'),
            5000,
        ));

        self::assertNull(
            $globexRepo->findById(new OrderId('order-1')),
            'globex must not see acme\'s order',
        );
        self::assertNotNull(
            $acmeRepo->findById(new OrderId('order-1')),
            'acme must still see its own order',
        );
    }

    #[Test]
    public function write_with_mismatched_tenant_id_is_rejected(): void
    {
        $acme = new TenantId('acme');
        $globex = new TenantId('globex');

        $globexRepo = new PdoOrderRepository(
            new TenantAwareConnection($this->pdo, $globex),
        );

        $orderForAcme = new Order(
            new OrderId('order-2'),
            $acme,
            new CustomerId('cust-1'),
            5000,
        );

        $this->expectException(CrossTenantWriteException::class);
        $globexRepo->save($orderForAcme);
    }
}

The first test would have caught the original Acme/Globex bug. The second test catches the more subtle one: the use case that loaded an aggregate under one tenant, held onto it through a service call, and tried to save it under another. Both run in milliseconds against in-memory SQLite. Both belong in CI as gates, not as advisories.

Add a third test that pokes the wrapper directly: pass it a query with no tenant_id and assert the LogicException. That is the regression test for the developer who, six months from now, adds a "quick fix" repository method and forgets the filter.

Where the strategies diverge

The repository above does row filtering. The seam is portable to the other two strategies without touching the domain or the repository.

For schema-per-tenant, TenantAwareConnection doesn't auto-bind tenant_id. Instead, on construction, it issues set search_path = tenant_acme, public (Postgres) or use acme (MySQL). The repository writes plain SQL with no WHERE tenant_id = ?. The isolation is enforced by the schema selection. The factory still resolves the tenant from TenantContext. The middleware doesn't change at all.

For connection-pool routing, the factory looks up the tenant's physical connection from a routing table (tenants.connection_url) and returns a TenantAwareConnection wrapping the right PDO. The repository is unchanged. The seam moves from query rewriting to connection selection — but TenantContext, TenantContextMiddleware, and the repository code stay identical.

This is the payoff of putting TenantId in the domain and the strategy in the adapter. You can migrate a noisy tenant onto its own host without touching a line of business code.

What you keep

The seam is four pieces:

TenantId as a domain value object, required on every aggregate that is tenant-scoped.
TenantContext as a request-scoped object, bound by middleware at the edge.
TenantAwareConnection as the only path from application code to the database, scoped to one tenant for its lifetime.
A repository that closes over the connection, asserts tenant match on writes, and is impossible to use cross-tenant.

The two tests — read isolation and write rejection — go in CI and stay there. Add a third for any new tenant-scoped aggregate.

What you do not keep is the habit of asking "did this query filter by tenant?" in code review. The wiring asks for you. Add the wrapper to the next repository you touch.

If this was useful

This is one chapter's worth of the seam patterns in Decoupled PHP — the book walks the same shape across HTTP, queues, external APIs, and the migration path from a framework-coupled service to a hexagonal one, with a runnable examples repo. The companion System Design Pocket Guide: Fundamentals covers the broader isolation question: schema-per-tenant vs row-filter vs database-per-tenant, with the trade-offs that drive the pick.

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

Pagination: Does It Belong in the Domain or in the Adapter?

Gabriel Anhaia — Tue, 19 May 2026 19:51:25 +0000

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

You sit down to add pagination to a list-orders endpoint. The domain has a clean OrderRepository port. You open it, and the first question hits before you've typed a character: what's the method signature?

public function listForCustomer(CustomerId $id, int $page, int $perPage): array;

Page and per-page. Simple. Until somebody complains that page 8000 of the admin export takes 14 seconds, and you realize you've baked OFFSET 80000 into the contract every consumer of this port now depends on. Switching to keyset pagination means changing the port. Changing the port means touching every adapter and every use case that calls it.

This is the pagination seam problem in hexagonal PHP. Pagination is half-domain and half-infrastructure, and most codebases get the line wrong. The domain doesn't care that the database can do offset scans; it cares that a list has an order, a size, and a way to ask for "what comes after this." The adapter cares about cursor encoding, index columns, and whether the underlying store can do keyset scans at all.

A Pagination value object lives in the domain. Cursor encoding, offset translation, and SQL belong in the adapter. The contract between them is a Page<T> return type that carries items and a nextCursor.

What the domain actually needs to say

The domain wants three things when it asks for a list:

A size. How many items per response. Capped.
A position. "From the start" or "after the thing the previous page ended on."
An ordering. The business decides the order. Newest first. Highest balance first. Alphabetical. The database does not get to pick.

Notice what's missing. There's no page number, no offset, no cursor string. Those are encodings, and encodings are an adapter concern. The domain says "give me the next 20 orders for this customer, newest first, starting after the one I last saw." The adapter figures out how to express that against PostgreSQL or DynamoDB or an in-memory fake.

Here's the Pagination value object in PHP 8.3, written exactly that way:

<?php

declare(strict_types=1);

namespace App\Domain\Common;

final readonly class Pagination
{
    public function __construct(
        public Limit $limit,
        public ?Cursor $after = null,
    ) {}

    public static function firstPage(int $limit): self
    {
        return new self(new Limit($limit), null);
    }

    public function after(Cursor $cursor): self
    {
        return new self($this->limit, $cursor);
    }
}

Limit is its own type because "an int between 1 and 100" is a domain rule, not a database rule. The cap is there to stop an API caller from asking for 50,000 rows. The floor is there because zero items isn't a page.

<?php

declare(strict_types=1);

namespace App\Domain\Common;

final readonly class Limit
{
    private const int MIN = 1;
    private const int MAX = 100;

    public int $value;

    public function __construct(int $value)
    {
        if ($value < self::MIN || $value > self::MAX) {
            throw new \DomainException(
                "Limit must be between "
                . self::MIN . " and " . self::MAX
                . ", got {$value}"
            );
        }
        $this->value = $value;
    }
}

Cursor is the part most people get wrong. It looks like it should hold an ID, or a timestamp, or a composite key. It shouldn't. From the domain's point of view, a cursor is an opaque token. The domain receives one from the previous page and hands it back to ask for the next. It never inspects the contents.

<?php

declare(strict_types=1);

namespace App\Domain\Common;

final readonly class Cursor
{
    public function __construct(public string $token)
    {
        if ($token === '') {
            throw new \DomainException('Cursor token cannot be empty');
        }
    }
}

That's a 20-line value object that holds a string. The reason it's a class and not a string parameter is type discipline. A Cursor can't accidentally be passed where a customer ID is expected, and the port signature reads like an English sentence. Same payoff you get from any tiny value object: the type checker does work the linter used to.

The port speaks domain, not SQL

With the value objects above, the repository port reads like the domain question it's answering:

<?php

declare(strict_types=1);

namespace App\Domain\Order;

use App\Domain\Common\Pagination;
use App\Domain\Customer\CustomerId;

interface OrderRepository
{
    public function listForCustomer(
        CustomerId $customerId,
        Pagination $pagination,
    ): Page;
}

And Page is a generic-ish carrier — PHP doesn't have proper generics, but the shape is:

<?php

declare(strict_types=1);

namespace App\Domain\Common;

final readonly class Page
{
    /**
     * @param list<object> $items
     */
    public function __construct(
        public array $items,
        public ?Cursor $nextCursor,
    ) {}

    public function hasMore(): bool
    {
        return $this->nextCursor !== null;
    }
}

That's the whole contract. items is what you asked for. nextCursor is null when you've reached the end and a fresh Cursor otherwise. The use case calling this port doesn't know whether the underlying store paginated by keyset, offset, or by hand-rolling row numbers. It hands back the cursor it received and asks for more.

A use case using it looks like this — note how plain it reads:

<?php

declare(strict_types=1);

namespace App\Application\Order;

use App\Domain\Common\Cursor;
use App\Domain\Common\Pagination;
use App\Domain\Customer\CustomerId;
use App\Domain\Order\OrderRepository;

final readonly class ListCustomerOrders
{
    public function __construct(
        private OrderRepository $orders,
    ) {}

    public function __invoke(
        string $customerId,
        int $limit,
        ?string $afterToken,
    ): array {
        $pagination = $afterToken === null
            ? Pagination::firstPage($limit)
            : Pagination::firstPage($limit)
                ->after(new Cursor($afterToken));

        $page = $this->orders->listForCustomer(
            new CustomerId($customerId),
            $pagination,
        );

        return [
            'items' => $page->items,
            'next' => $page->nextCursor?->token,
        ];
    }
}

No SQL. No OFFSET. No mention of how the rows come back. The HTTP adapter on top of this is the one that exposes ?after= and ?limit= query parameters; the domain pulls back to its proper job, which is describing what a list is.

The adapter does the SQL — keyset pagination, base64 cursors

Now for the half nobody talks about cleanly: the adapter. The cursor token is opaque to the domain, but it has to mean something concrete to the database. For keyset (also called "seek") pagination, the cursor encodes the position of the last row returned. For an order list sorted by (created_at DESC, id DESC), that's (created_at, id) of the final row.

Encode it as base64 JSON so it stays URL-safe and you can extend the encoded fields later without breaking older clients:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence\Order;

use App\Domain\Common\Cursor;

final readonly class OrderCursorCodec
{
    public function encode(\DateTimeImmutable $createdAt, string $id): Cursor
    {
        $payload = [
            'c' => $createdAt->format(\DateTimeInterface::RFC3339_EXTENDED),
            'i' => $id,
        ];
        $json = json_encode($payload, JSON_THROW_ON_ERROR);
        return new Cursor(
            rtrim(strtr(base64_encode($json), '+/', '-_'), '=')
        );
    }

    /**
     * @return array{0: \DateTimeImmutable, 1: string}
     */
    public function decode(Cursor $cursor): array
    {
        $b64 = strtr($cursor->token, '-_', '+/');
        $b64 .= str_repeat('=', (4 - strlen($b64) % 4) % 4);
        $json = base64_decode($b64, true);
        if ($json === false) {
            throw new \InvalidArgumentException('Malformed cursor');
        }
        $data = json_decode($json, true, flags: JSON_THROW_ON_ERROR);
        return [
            new \DateTimeImmutable($data['c']),
            (string) $data['i'],
        ];
    }
}

The codec lives in the infrastructure namespace. The domain never imports it. If a future migration moves orders from PostgreSQL to a different store with different sort columns, the codec changes, and the port doesn't.

The repository itself ties the pieces together:

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence\Order;

use App\Domain\Common\Page;
use App\Domain\Common\Pagination;
use App\Domain\Customer\CustomerId;
use App\Domain\Order\Order;
use App\Domain\Order\OrderRepository;
use Doctrine\DBAL\Connection;

final readonly class DoctrineOrderRepository implements OrderRepository
{
    public function __construct(
        private Connection $db,
        private OrderCursorCodec $cursors,
        private OrderHydrator $hydrator,
    ) {}

    public function listForCustomer(
        CustomerId $customerId,
        Pagination $pagination,
    ): Page {
        $sql = 'SELECT id, customer_id, total_cents, created_at
                FROM orders
                WHERE customer_id = :customer_id';
        $params = ['customer_id' => $customerId->value];

        if ($pagination->after !== null) {
            [$afterCreatedAt, $afterId] = $this->cursors->decode(
                $pagination->after
            );
            $sql .= ' AND (created_at, id) < (:after_created, :after_id)';
            $params['after_created'] = $afterCreatedAt->format(
                'Y-m-d H:i:s.uP'
            );
            $params['after_id'] = $afterId;
        }

        $sql .= ' ORDER BY created_at DESC, id DESC LIMIT :limit';
        $params['limit'] = $pagination->limit->value + 1;

        $rows = $this->db->fetchAllAssociative($sql, $params);

        $hasMore = count($rows) > $pagination->limit->value;
        if ($hasMore) {
            array_pop($rows);
        }

        $orders = array_map(
            fn (array $row): Order => $this->hydrator->fromRow($row),
            $rows,
        );

        $next = null;
        if ($hasMore && $rows !== []) {
            $last = end($rows);
            $next = $this->cursors->encode(
                new \DateTimeImmutable($last['created_at']),
                (string) $last['id'],
            );
        }

        return new Page($orders, $next);
    }
}

The LIMIT :limit + 1 is the standard keyset "do I have more?" probe. Fetch one extra row; if you got it, there's a next page and the extra row tells you the cursor for it.

The (created_at, id) < (:after_created, :after_id) row-value comparison is the part that makes keyset pagination work correctly when timestamps collide. PostgreSQL, MySQL 8.0+, and SQLite all support this syntax. If your stack doesn't, fall back to created_at < :a OR (created_at = :a AND id < :b) — same shape, more verbose.

The in-memory fake — why this layout pays off in tests

Because the port doesn't mention SQL or cursors, the in-memory test double is honest about its own shape:

<?php

declare(strict_types=1);

namespace App\Tests\Doubles;

use App\Domain\Common\Cursor;
use App\Domain\Common\Page;
use App\Domain\Common\Pagination;
use App\Domain\Customer\CustomerId;
use App\Domain\Order\Order;
use App\Domain\Order\OrderRepository;

final class InMemoryOrderRepository implements OrderRepository
{
    /** @var array<string, list<Order>> */
    private array $byCustomer = [];

    public function add(Order $order): void
    {
        $this->byCustomer[$order->customerId->value][] = $order;
    }

    public function listForCustomer(
        CustomerId $customerId,
        Pagination $pagination,
    ): Page {
        $rows = $this->byCustomer[$customerId->value] ?? [];
        usort(
            $rows,
            fn (Order $a, Order $b) => $b->createdAt <=> $a->createdAt,
        );

        $start = 0;
        if ($pagination->after !== null) {
            $start = (int) $pagination->after->token + 1;
        }

        $slice = array_slice($rows, $start, $pagination->limit->value);
        $next = ($start + count($slice)) < count($rows)
            ? new Cursor((string) ($start + count($slice) - 1))
            : null;

        return new Page($slice, $next);
    }
}

The fake's cursor token is just a numeric index. That's fine. It's opaque to the domain, the domain doesn't peek inside, and tests never assert on the string. Two adapters, two encodings, one contract. The use case test doesn't care which one is wired in.

What you keep, what you push out

Keep in the domain:

Pagination, Limit, Cursor, Page. Four value objects, all immutable, all readonly.
Ordering decisions when they're a business rule (newest first, by amount, by status). When the order is "whatever the database returns," it's not a domain rule and it doesn't belong here either — but that's a separate post.
The port signature: it takes a Pagination, it returns a Page. No int $page, no string $cursor, ever.

Push to the adapter:

Cursor encoding. Base64 JSON, signed JWT, raw column tuple. Adapter's call.
The choice of keyset vs offset vs Mongo _id-greater-than. Different stores, different mechanics, same port.
The +1 probe, the row-value comparison, the index hint, the explain plan.

The seam is small and it holds. When somebody complains about page-8000 latency a year from now, you change one adapter file, write a migration to drop the offset code path, and ship. The use case doesn't know it happened. The HTTP contract doesn't break, and the cursor is still a string, still opaque, still works.

That's what hexagonal pays you for: the ability to swap an implementation that's hurting you without rewriting the ten things that depend on it.

If this was useful

Where to draw the line between domain and adapter is the question every chapter of Decoupled PHP circles back to. Pagination is one of the cleaner examples; transactions, error translation, and event delivery are messier and get their own chapters. If you've ever stared at a port signature wondering whether to put SQL-shaped types in it, the book is built around getting that decision right by default.

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

ULID and UUID v7 in PHP: Modern IDs for Domain Entities

Gabriel Anhaia — Tue, 19 May 2026 19:51:01 +0000

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

You write INSERT INTO orders (...) VALUES (...) and Postgres hands you back RETURNING id. The handler grabs the integer, sticks it on the response, you ship the JSON. It works. It has worked for fifteen years.

Then the team adds a queue worker that creates the order in one service and reads it from another a few milliseconds later. The producer needs to publish the event with an ID. The consumer needs to find the row by that ID. Neither can wait for a database round-trip to learn what the ID is. So the team starts threading the auto-increment value through three systems, or worse, builds a synchronous "create then fan-out" flow that pretends the database is the source of truth for ordering.

The fix is older than the problem. Pick an ID scheme the application owns, not the database. ULID and UUID v7 are the two formats that earn that job in PHP today. Both are 128-bit and time-sortable. You can generate them anywhere and drop them straight into a BINARY(16) column or a Postgres uuid. This post walks the working code for both, wraps them as value objects, and shows where each one falls down.

Why auto-increment hurts past a single service

The auto-increment column is fine when one process writes one table. It breaks in three predictable ways:

You can't know the ID until after the insert. Outbox patterns, idempotent retries, and event publishing all want to construct the entity, give it identity, and then persist. A round-trip to learn the ID inverts that order.
The ID leaks ordering and rate. A competitor scraping /orders/41832 then /orders/41835 three seconds later learns your throughput. The BIGSERIAL is a public counter.
Sharding and merging fall over. Two databases can't safely both own the same sequence. The moment you split a single table across regions, the integer key becomes the worst data-migration job you'll ever do.

UUID v4 fixes points 1 and 2 (it's random, 128 bits, generated anywhere) but breaks the index. B-tree inserts on random keys fragment the leaf pages, and once the working set leaves RAM the write amplification gets ugly. The UUID v7 RFC calls this out directly: random UUIDs hurt insert locality once the table is bigger than the buffer pool, which is the whole reason v7 puts the timestamp in the high bits.

ULID and UUID v7 keep the "generate anywhere" win and put the timestamp in the high bits, so newly inserted rows append to the index instead of scattering across it. You get the application-side identity model without the index regression.

The two formats, side by side

Both are 128 bits. Both put a millisecond timestamp in the leading 48 bits. The rest is random.

ULID:     01HQZK9VBM7N3X5T8R2Q4Y6W8E
          ^^^^^^^^^^^^^^^^^^^^^^^^^^
          ^^^^^^^^^^ 48-bit time (10 base32 chars)
                    ^^^^^^^^^^^^^^^^ 80-bit random (16 base32 chars)
          (Crockford base32, 26 chars total)

UUID v7:  01951a3c-7b00-7a8c-9f4e-3d2b1c0a8f7e
          ^^^^^^^^^^^^^
          48-bit time (first 12 hex chars)
                        ^^^^^^^^^^^^^^^^^^^^^^^
                        74 random + 6 version/variant bits
          (hex with dashes, 36 chars total)

What's actually different:

Wire format. ULID's Crockford base32 is shorter (26 chars vs 36) and case-insensitive without ambiguity (no I, L, O, U). UUID v7 looks like every other UUID, so it pastes cleanly into anything that already speaks UUID.
Database support. Postgres has a native uuid type. MySQL has BINARY(16). Both store 16 bytes either way. For UUID v7 in Postgres 8.2+ the type is built in; ULID needs an extension or a bytea/char(26) decision.
Standards. UUID v7 is in RFC 9562 (May 2024, finalized after years as a draft). ULID has a spec on GitHub but no IETF RFC.
Library reach. Every language has a UUID library; many have v7 now. ULID has libraries everywhere too, but adoption is thinner outside the JS/Node and PHP ecosystems.

For a greenfield PHP service in 2026, UUID v7 is the safer pick: it's RFC-backed, has a native Postgres type, and is the most widely tooled. ULID is the better pick when the ID will be copy-pasted by humans (support tickets, URLs, log greps) or when you want the shorter string form.

The rest of this post uses UUID v7 in the code samples and notes the ULID swap at the end.

Generating UUID v7 with `ramsey/uuid`

The ramsey/uuid library added native UUID v7 support in version 4.7. Install it once:

composer require ramsey/uuid:^4.7

Generate one:

<?php

declare(strict_types=1);

use Ramsey\Uuid\Uuid;

$id = Uuid::uuid7();
echo $id->toString();
// 01951a3c-7b00-7a8c-9f4e-3d2b1c0a8f7e

That's the whole API. The library reads the current millisecond, packs it into the leading 48 bits, sets the version (7) and variant bits, and fills the rest with cryptographic random bytes from random_bytes(). No external service, no DB round-trip, no clock-skew committee.

You can pass a DateTimeInterface if you need a backdated ID for migrations or tests:

$id = Uuid::uuid7(new DateTimeImmutable('2026-01-01T00:00:00Z'));

Wrapping the ID as a value object

A raw Uuid object is fine for one-off scripts. In a service with a domain layer, you want every domain entity to have its own ID type (OrderId, CustomerId, InvoiceId) so the type system catches a swap before it reaches production.

The pattern is a thin readonly class around the string form, with three named constructors:

<?php

declare(strict_types=1);

namespace App\Order\Domain;

use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;

final readonly class OrderId
{
    private function __construct(public string $value) {}

    public static function generate(): self
    {
        return new self(Uuid::uuid7()->toString());
    }

    public static function fromString(string $value): self
    {
        $uuid = Uuid::fromString($value);
        if ($uuid->getFields()->getVersion() !== 7) {
            throw new \InvalidArgumentException(
                "OrderId must be UUID v7, got version "
                . $uuid->getFields()->getVersion()
            );
        }
        return new self($uuid->toString());
    }

    public static function fromBytes(string $bytes): self
    {
        return new self(Uuid::fromBytes($bytes)->toString());
    }

    public function toBytes(): string
    {
        return Uuid::fromString($this->value)->getBytes();
    }

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

    public function __toString(): string
    {
        return $this->value;
    }
}

Three things to notice.

generate() is a static factory, not a constructor. The constructor is private. Code reading this class never wonders whether new OrderId() creates a new ID or wraps an existing one. There is no new OrderId().
fromString() validates the version. A v4 UUID passed in by mistake will throw at the boundary, not after it has corrupted three downstream tables.
toBytes() exists for the database. Storing UUIDs as text wastes 20 bytes per row and slows the index. The binary form is what the persistence adapter wants.

The entity now owns its identity from the moment it is constructed:

final readonly class Order
{
    public function __construct(
        public OrderId $id,
        public CustomerId $customerId,
        public Money $total,
        public DateTimeImmutable $createdAt,
    ) {}

    public static function place(
        CustomerId $customer,
        Money $total,
        DateTimeImmutable $now,
    ): self {
        return new self(
            id: OrderId::generate(),
            customerId: $customer,
            total: $total,
            createdAt: $now,
        );
    }
}

Order::place() returns a fully-formed order with a permanent ID, before any database has been touched. The handler can publish the OrderPlaced event with order.id and trust the consumer will find the row when persistence finishes.

Persisting to Postgres

Postgres has a native uuid column type that stores 16 bytes and accepts the canonical hex-with-dashes form on input:

CREATE TABLE orders (
    id           uuid PRIMARY KEY,
    customer_id  uuid NOT NULL,
    total_cents  bigint NOT NULL,
    currency     char(3) NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now()
);

The adapter is plain PDO. No ORM annotations, no custom Doctrine type. Bind the string form:

<?php

declare(strict_types=1);

namespace App\Order\Adapter\Persistence;

use App\Order\Domain\Order;
use App\Order\Domain\OrderRepository;
use PDO;

final readonly class PostgresOrderRepository implements OrderRepository
{
    public function __construct(private PDO $pdo) {}

    public function save(Order $order): void
    {
        $stmt = $this->pdo->prepare(
            'INSERT INTO orders
             (id, customer_id, total_cents, currency, created_at)
             VALUES (:id, :customer_id, :total, :currency, :created_at)'
        );
        $stmt->execute([
            'id'          => $order->id->value,
            'customer_id' => $order->customerId->value,
            'total'       => $order->total->cents,
            'currency'    => $order->total->currency,
            'created_at'  => $order->createdAt->format('c'),
        ]);
    }

    public function find(OrderId $id): ?Order
    {
        $stmt = $this->pdo->prepare(
            'SELECT id, customer_id, total_cents, currency, created_at
             FROM orders WHERE id = :id'
        );
        $stmt->execute(['id' => $id->value]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        if ($row === false) {
            return null;
        }
        return new Order(
            id:         OrderId::fromString($row['id']),
            customerId: CustomerId::fromString($row['customer_id']),
            total:      Money::of((int) $row['total_cents'], $row['currency']),
            createdAt:  new \DateTimeImmutable($row['created_at']),
        );
    }
}

Two production notes.

MySQL. No native uuid type. Use BINARY(16) and bind $order->id->toBytes() instead of the string form. The 16-byte form sorts identically to the string form because the timestamp is at the top.
Doctrine. If you must use it, ramsey/uuid-doctrine provides a uuid and uuid_binary type. Map the entity's OrderId through a custom type so the conversion stays at the persistence edge, not in the domain.

Time-sorted, by design

Because the timestamp is the high-order 48 bits, an ORDER BY id returns rows in roughly creation order:

SELECT id, total_cents, created_at
FROM orders
WHERE customer_id = '01951a3c-7b00-7a8c-9f4e-3d2b1c0a8f7e'
ORDER BY id DESC
LIMIT 20;

That query uses the primary-key index directly. No extra index on created_at. No secondary sort. The "newest first" pagination most apps need is the natural sort of the key.

Two caveats worth knowing:

Same-millisecond ordering is random. Two IDs generated in the same millisecond on the same machine will not preserve creation order. If you need strict creation ordering inside a millisecond, add a sequence column or use the spec's monotonic counter variant (ULID supports this; UUID v7 has optional method 1 monotonicity that ramsey/uuid does not enable by default).
Clock skew across hosts. If two servers disagree on the time by 200 ms, IDs from the lagging server will sort behind newer IDs from the fast one. NTP usually keeps this under 10 ms, which is fine for "newest first" UX but not for anything that needs strict global ordering.

For the latter, a database sequence is still the right answer. ULID and UUID v7 give you "good enough for the UI" sort, not a Lamport clock.

Swapping in ULID

If you decide ULID is a better fit (shorter, more human-friendly), the value object barely changes. With symfony/uid, which ships ULID support:

use Symfony\Component\Uid\Ulid;

final readonly class OrderId
{
    private function __construct(public string $value) {}

    public static function generate(): self
    {
        return new self((new Ulid())->toBase32());
    }

    public static function fromString(string $value): self
    {
        if (!Ulid::isValid($value)) {
            throw new \InvalidArgumentException("Invalid ULID: $value");
        }
        return new self($value);
    }

    public function toBytes(): string
    {
        return Ulid::fromString($this->value)->toBinary();
    }
}

Storage in Postgres becomes bytea or char(26). In MySQL, still BINARY(16). The domain code that calls OrderId::generate() does not change. That is the payoff of the value-object wrapper: the entity does not know which format won the meeting.

When not to do this

A few cases where the auto-increment integer is still the right pick:

A single-process internal tool with one writer and no events.
Tables you never expose over an API and never replicate.
Bulk import staging tables you'll drop next week.

For anything else, generate the ID in the application and wrap it as a value object. Outbox, event bus, second region, public URL, forecasted shard: any of those, and the database stops being the owner of identity. It becomes one of the things that store it.

If this was useful

This is the slice of Decoupled PHP where identity, persistence, and the dependency rule meet. The book takes the same value-object shape through the rest of the domain (Money, EmailAddress, OrderStatus) and shows how the persistence adapter stays a 30-line PDO class instead of an ORM annotation hairball. Database Playbook is the companion when the question is which store deserves the table in the first place.

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

DTOs vs Value Objects: When to Use Which in PHP

Gabriel Anhaia — Tue, 19 May 2026 19:50:38 +0000

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 pull request lands in review. Someone added a class called OrderData. It has a customerId string, an amount int, a currency string, and a toArray() method. It's used by the HTTP controller to receive the request body, by the use case as its input, by the repository to map to a row, and by the response serializer to build the JSON reply. One class, four jobs.

The reviewer asks the question every PHP team eventually argues about: is this a DTO or a value object?

The honest answer is that it's neither, and that's the bug. The names matter because the responsibilities are different. Pin down which side of the boundary the type lives on and the decision becomes mechanical.

The one rule

A DTO (Data Transfer Object) carries data across a boundary. HTTP request body to use case input. Use case output to API response. Background job payload to worker. It has no behavior beyond construction. It is allowed to be naive about validity. Its job is transport. Guarantees belong elsewhere.

A value object lives inside the domain and represents a concept with rules. Money, EmailAddress, Sku, Coordinate. Two value objects with the same fields are equal. Identity does not apply. The instance is immutable. It refuses to exist in an invalid state; the constructor throws.

The rule:

If it crosses a boundary, it's a DTO. If it carries meaning inside the domain, it's a value object.

That's it.

The DTO: `CreateOrderInput`

A DTO is shaped by the boundary it serves. The HTTP controller decodes a JSON body into one of these, hands it to the use case, and that's the end of the DTO's career. It is a courier.

<?php

declare(strict_types=1);

namespace App\Application\Order\Input;

final readonly class CreateOrderInput
{
    /**
     * @param list<CreateOrderLineInput> $lines
     */
    public function __construct(
        public string $customerId,
        public array $lines,
        public string $currency,
        public ?string $couponCode = null,
    ) {}

    public static function fromArray(array $payload): self
    {
        $lines = array_map(
            static fn (array $line) => new CreateOrderLineInput(
                sku: (string) $line['sku'],
                quantity: (int) $line['quantity'],
                unitPriceMinor: (int) $line['unit_price_minor'],
            ),
            $payload['lines'] ?? [],
        );

        return new self(
            customerId: (string) $payload['customer_id'],
            lines: $lines,
            currency: (string) $payload['currency'],
            couponCode: isset($payload['coupon_code'])
                ? (string) $payload['coupon_code']
                : null,
        );
    }
}

final readonly class CreateOrderLineInput
{
    public function __construct(
        public string $sku,
        public int $quantity,
        public int $unitPriceMinor,
    ) {}
}

Notice what is not there:

No isValid() method. Validation belongs to the layer that owns the rules, not to the courier.
No business behavior. CreateOrderInput::total() is the wrong place for that math, because the DTO doesn't know what a valid total looks like. It doesn't know currencies, rounding, or whether quantities can be negative.
No domain types. The currency is a string. The quantity is an int. The DTO speaks the language of the HTTP boundary: JSON and primitives. The domain language stays out.

readonly makes them immutable after construction. final blocks subclassing. Named constructors like fromArray keep the main constructor free for callers that already have typed inputs.

If you have an output DTO going the other way (OrderConfirmedOutput), it follows the same shape: primitives, no behavior, named constructor that builds it from a domain object.

The value object: `Money`

A value object is shaped by the domain rule it protects. Money is the classic example because everyone gets it wrong with floats, and the wrong version produces silent bugs in invoicing for years.

<?php

declare(strict_types=1);

namespace App\Domain\Shared;

final readonly class Money
{
    public function __construct(
        public int $amountMinor,
        public Currency $currency,
    ) {
        if ($amountMinor < 0) {
            throw new \DomainException(
                'Money cannot be negative; use a Refund or signed Ledger entry.',
            );
        }
    }

    public static function zero(Currency $currency): self
    {
        return new self(0, $currency);
    }

    public function add(self $other): self
    {
        $this->assertSameCurrency($other);
        return new self($this->amountMinor + $other->amountMinor, $this->currency);
    }

    public function subtract(self $other): self
    {
        $this->assertSameCurrency($other);
        if ($other->amountMinor > $this->amountMinor) {
            throw new \DomainException('Subtraction would produce negative Money.');
        }
        return new self($this->amountMinor - $other->amountMinor, $this->currency);
    }

    public function multiply(int $quantity): self
    {
        if ($quantity < 0) {
            throw new \DomainException('Cannot multiply Money by a negative quantity.');
        }
        return new self($this->amountMinor * $quantity, $this->currency);
    }

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

    private function assertSameCurrency(self $other): void
    {
        if ($this->currency !== $other->currency) {
            throw new \DomainException(
                "Currency mismatch: {$this->currency->value} vs {$other->currency->value}",
            );
        }
    }
}

enum Currency: string
{
    case EUR = 'EUR';
    case USD = 'USD';
    case GBP = 'GBP';
    case BRL = 'BRL';
}

What makes this a value object and not a DTO:

Invalid states are refused. Negative amounts throw. Currency mismatches throw. You cannot hold a Money(-100, EUR) instance, ever.
Behavior is tied to the concept. add, subtract, multiply. Each one returns a new Money because the object is immutable. No method mutates $this.
Comparison is by value. Money(500, EUR)->equals(Money(500, EUR)) is true. They're interchangeable.
Domain types replace primitives. Currency is an enum, not a string. The compiler enforces the closed set.
There is no identity. No id. Two equal Money objects are the same Money for all purposes.

If you find yourself writing Money(-100, ...) somewhere, that is a signal: you wanted a different concept. A Refund, a LedgerEntry with a sign, a Discount. You can't construct a negative Money. The compiler stops you before runtime does.

The conversion: where they meet

The DTO and the value object never overlap inside the application. They meet at exactly one place: the application boundary, where the use case (or a thin mapper next to it) translates between the two.

<?php

declare(strict_types=1);

namespace App\Application\Order;

use App\Application\Order\Input\CreateOrderInput;
use App\Domain\Order\Order;
use App\Domain\Order\OrderId;
use App\Domain\Order\OrderLine;
use App\Domain\Order\Sku;
use App\Domain\Shared\Currency;
use App\Domain\Shared\Money;

final readonly class CreateOrderUseCase
{
    public function __construct(
        private OrderRepository $orders,
        private IdGenerator $ids,
    ) {}

    public function handle(CreateOrderInput $input): OrderId
    {
        $currency = Currency::from($input->currency);

        $lines = array_map(
            static fn ($line) => new OrderLine(
                sku: new Sku($line->sku),
                quantity: $line->quantity,
                unitPrice: new Money($line->unitPriceMinor, $currency),
            ),
            $input->lines,
        );

        $order = Order::place(
            id: $this->ids->next(),
            customerId: $input->customerId,
            lines: $lines,
        );

        $this->orders->save($order);

        return $order->id();
    }
}

Three things happen at the boundary:

Primitives become domain types. $input->currency (string) becomes Currency::EUR (enum). $line->unitPriceMinor (int) becomes a Money. The string-to-enum conversion is where invalid currencies get caught: Currency::from('XYZ') throws.
Domain rules engage. The Money constructor rejects negatives. The Sku constructor rejects empty strings. The Order::place named constructor enforces whatever invariants the order has (at least one line, total above zero, etc.). If anything is wrong, the use case throws a domain exception before anything is persisted.
The DTO is discarded. Past this point, no code holds a reference to CreateOrderInput. The order lives in the domain as an Order aggregate built from value objects. The DTO did its job. It carried the request across the wall.

The same shape applies in reverse. The query side builds a read-model DTO from the domain (or directly from a SQL row), and the HTTP layer serializes it. The domain object never leaks to JSON.

What goes wrong when you mix them

The god-DTO pattern from the opening (one OrderData doing four jobs) fails in three predictable ways.

Validation leaks into the wrong layer. When the controller's request object is the same class the domain uses, you end up either validating in the controller, so the domain trusts unvalidated input, or validating in the domain, so the HTTP layer can't reject a malformed payload with a 400 before any business code runs. Splitting the types lets each layer enforce what it owns: the DTO is shape-checked by the HTTP framework, the value object is rule-checked by its constructor.

The wire format dictates the domain. Say the JSON schema changes. Currency becomes an object with code and symbol. Amounts move to strings to avoid float weirdness in JavaScript. If the same class is used internally, the domain has to change too. With a DTO at the boundary, the wire format changes, the fromArray mapper changes, and the domain doesn't move.

Equality becomes ambiguous. OrderData(500, 'EUR') == OrderData(500, 'EUR'). Are these the same? In PHP, == on objects compares property by property. That works by accident. Then someone adds a ?DateTimeImmutable $createdAt and now two structurally-identical requests are no longer "equal" because one was built a microsecond later. Value objects own their own equals() method; DTOs don't need one because they're not compared.

A decision table

When you're staring at a new class and wondering which it is, walk this list:

Question	DTO	Value Object
Does it cross a boundary (HTTP, queue, DB row, external API)?	yes	no
Does it represent a domain concept with rules?	no	yes
Can it exist in an invalid state?	yes (validation is the next layer's job)	no (constructor throws)
Does it have behavior beyond construction?	no	yes
Is it compared by value?	no	yes
Does it use primitive types?	yes (strings, ints)	no (enums, value objects)
Is it immutable?	yes	yes

Immutability is the only row they share. Everything else points the type at a different layer. A few honest edge cases follow.

A bare Uuid class. Looks like a value object (immutable, equals by value, constructor validates the format). It is. The fact that it also rides along inside DTOs is fine. Value objects are allowed to appear inside DTOs as fields, as long as the DTO doesn't add behavior on top of them. The reverse is forbidden: DTOs never appear inside the domain.
Read models. A CustomerSummaryView returned by a query handler is a DTO, even if it never crosses an HTTP wire. It crosses the boundary from the query layer to the caller. Same rules apply.
Form requests in Laravel / Symfony. These are framework-flavored DTOs. The framework handles shape and basic validation; you map them into a clean CreateOrderInput before handing to the use case so the use case doesn't import the framework.

The migration path when you're already mixed up

Most PHP codebases that hit this problem start with the god-DTO pattern. The cleanup is incremental, not a freeze-week rewrite:

Pick the worst offender. Usually the entity at the center of the busiest use case: Order, User, Invoice. The one that has toArray, fromRequest, fillFromEloquent, and validate all on the same class.
Introduce the input DTO first. Add CreateOrderInput as a new class. Change the controller to build it. Change the use case signature to accept it. The domain object stays put for now. Tests still pass because nothing about the persistence layer has moved.
Introduce the first value object. Pick the field with the most rule density: usually Money, an email, or an identifier. Replace the primitive everywhere it appears in the domain. The DTO still carries the primitive; the conversion happens in the use case.
Repeat per field, per use case. Each round leaves the codebase compiling and the tests green. Stop whenever the marginal value object stops earning its place. Not every string needs a wrapper.

You will know it's working when a new field added to the JSON request never causes a change to the domain. When you can change the JSON schema without touching the domain, the split is working.

What you keep, what you drop

Keep DTOs at every boundary you control: HTTP in, HTTP out, queue payload, external API client, database row. Keep value objects at every domain concept that has rules. Keep one thin conversion step at the boundary, owned by the use case (or a mapper class next to it). Both stay immutable, both stay final, both get named constructors when the construction is non-trivial.

Drop classes that try to be a DTO and an entity at the same time. Drop validation methods on DTOs. Drop behavior methods on DTOs. Drop primitive obsession inside the domain: string $currency is a code smell once you have an enum.

The naming argument stops mattering once the layers do. Call them whatever your team agrees on. Just don't let one class do both jobs.

If this was useful

This is one slice of the boundary discipline the rest of the book is built on. Decoupled PHP walks the full layout — ports and adapters, use cases, the dependency rule, and the migration playbook for a Laravel or Symfony codebase that already mixed it all together. If your storage layer is where the pain lives, Database Playbook is the companion: choosing the right store for each system you build, and not letting the schema dictate the domain.

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

Authorization in Use Cases, Not Controllers

Gabriel Anhaia — Tue, 19 May 2026 19:50:10 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: System Design Pocket Guide: Fundamentals
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You've shipped the feature. The HTTP route is locked down. There's a Gate::authorize('refund', $order) line at the top of the controller. Code review passed. The Laravel Policy has unit tests. Everything is green.

Six months later somebody opens a Jira ticket: "we need to refund orders from the back-office CLI." Two weeks after that, the payment provider starts sending refund-completed webhooks that have to flip the same order state. A queue worker shows up to retry failed refunds in batch.

Three new entry points. Same business operation. Same authorization rules. The controller has one of them. The other three either copy-paste the Policy call, or (more often) forget it entirely and ship a php artisan refund:order command that lets any operator with shell access refund anyone's order without a check.

The auth logic was in the wrong layer. That's the whole bug. And it's a bug that the framework's own conventions push you into.

The framework example that teaches you the wrong place

Open the Laravel docs for authorization. The canonical example puts the check in the controller:

namespace App\Http\Controllers;

use App\Models\Order;
use Illuminate\Http\Request;

final class RefundController
{
    public function store(Request $request, Order $order)
    {
        $this->authorize('refund', $order);

        $order->refund($request->integer('amount_cents'));

        return response()->noContent();
    }
}

Symfony's documentation does the same thing with Voters and the #[IsGranted] attribute on the controller method:

namespace App\Controller;

use App\Entity\Order;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted;

final class RefundController extends AbstractController
{
    #[Route('/orders/{id}/refund', methods: ['POST'])]
    #[IsGranted('REFUND', subject: 'order')]
    public function refund(Order $order, Request $request): Response
    {
        $amount = (int) $request->request->get('amount_cents');
        $order->refund($amount);

        return new Response('', Response::HTTP_NO_CONTENT);
    }
}

Both examples are correct as far as the HTTP layer goes. Both teach the wrong layer.

The controller is an adapter. It translates an HTTP request into a call against your application. Putting the rule "only a manager can refund an order over 500 EUR" inside the adapter says: this rule exists because of HTTP. Which it does not. It exists because the business needs it. HTTP is one of the rooms where the rule applies.

The day a second entry point arrives

Here is the same RefundOrder operation reached from php artisan. No middleware. No $request->user(). No Policy invocation, because nothing in the Symfony or Laravel example told the engineer that the auth check belonged anywhere except the controller.

namespace App\Console\Commands;

use App\Models\Order;
use Illuminate\Console\Command;

final class RefundOrderCommand extends Command
{
    protected $signature = 'refund:order
        {order_id}
        {amount_cents : Refund amount in cents}
        {--operator= : Operator initiating the refund}';

    public function handle(): int
    {
        $order = Order::findOrFail($this->argument('order_id'));
        $order->refund((int) $this->argument('amount_cents'));

        $this->info("Refunded {$order->id}");
        return self::SUCCESS;
    }
}

The --operator= flag is informational. Nothing in this code verifies the operator is allowed. Anyone with shell access on the box can refund anything. The Policy that gates the HTTP route is not invoked. The Voter is not invoked. The authorize() helper is not even available — there's no Auth::user() in a console context unless you wired one up.

The same hole exists when a queue worker processes a RefundOrderJob you dispatched from somewhere else, and when an inbound webhook from the payment provider calls OrderService::refund() directly because "the webhook is trusted." The webhook handler ships without the check three months after the CLI did.

The OWASP API Security Top 10 (2023) lists "broken function level authorization" as risk #5. The pattern is exactly this: the rule lives only on the public HTTP path, and an internal path skips it.

Move the rule to where the rule lives

A use case is one business operation. The rule that gates it belongs inside it. If the rule is "you must be a manager to refund over 500 EUR," it belongs inside RefundOrder, not on top of one of the doors that lead to it.

Three pieces:

An AuthorizationPort: an interface the use case depends on. It does not know about Auth::user(), JWTs, sessions, or HTTP headers. It just answers "can this actor do this action on this subject?"
An Actor value object: who is asking. Each adapter builds one its own way (HTTP from the session, CLI from the OS user, queue from whoever dispatched the job, webhook from a verified signature plus a service identity).
The use case itself, which takes an Actor as part of its input and calls the port before doing anything mutating.

namespace App\Domain\Auth;

interface AuthorizationPort
{
    public function authorize(Actor $actor, string $action, object $subject): void;
}

final readonly class Actor
{
    public function __construct(
        public string $id,
        public string $kind,
        public array $roles,
    ) {}

    public static function system(string $name): self
    {
        return new self(id: "system:{$name}", kind: 'system', roles: ['system']);
    }
}

final class NotAuthorized extends \DomainException {}

Actor::system() is the escape hatch for things like the payment-provider webhook, where the caller is a verified service rather than a human. It still goes through the same port; it just produces an actor whose roles include system. The port decides what system can do, the same way it decides what manager can do.

The use case looks like this:

namespace App\UseCase;

use App\Domain\Auth\Actor;
use App\Domain\Auth\AuthorizationPort;
use App\Domain\Order\OrderRepository;

final readonly class RefundOrder
{
    public function __construct(
        private OrderRepository $orders,
        private AuthorizationPort $auth,
    ) {}

    public function execute(
        Actor $actor,
        string $orderId,
        int $amountCents,
    ): void {
        $order = $this->orders->getById($orderId);

        $this->auth->authorize($actor, 'order.refund', $order);

        $order->refund($amountCents);
        $this->orders->save($order);
    }
}

One authorization line. It runs no matter who called execute(). The use case does not know HTTP exists; it does not know Artisan exists; it does not know a queue exists. It knows about an Actor, an order, and a port.

The adapter (Laravel Policy) implements the port

The Laravel Policy doesn't disappear. It moves behind the port. Same code, different caller:

namespace App\Infrastructure\Auth;

use App\Domain\Auth\Actor;
use App\Domain\Auth\AuthorizationPort;
use App\Domain\Auth\NotAuthorized;
use App\Models\Order;
use App\Policies\OrderPolicy;

final readonly class LaravelPolicyAuthorization implements AuthorizationPort
{
    public function __construct(private OrderPolicy $policy) {}

    public function authorize(Actor $actor, string $action, object $subject): void
    {
        $allowed = match (true) {
            $action === 'order.refund' && $subject instanceof Order
                => $this->policy->refund($actor, $subject),
            default => false,
        };

        if (! $allowed) {
            throw new NotAuthorized("{$actor->id} cannot {$action}");
        }
    }
}

The Policy still encodes the business rules: managers, refund caps, regional restrictions. It is now invoked from the use case, not from the controller. Symfony Voters work the same way: wrap Security::isGranted() (or call the voter directly) inside an AuthorizationPort implementation and bind it in the container.

The controller becomes pure routing:

final class RefundController
{
    public function __construct(private RefundOrder $useCase) {}

    public function store(Request $request, string $orderId): Response
    {
        $this->useCase->execute(
            actor: HttpActor::fromRequest($request),
            orderId: $orderId,
            amountCents: $request->integer('amount_cents'),
        );

        return response()->noContent();
    }
}

Five lines: parse input, build an actor, call the use case. No authorize() because the use case owns it.

The CLI command now fails closed

final class RefundOrderCommand extends Command
{
    protected $signature = 'refund:order
        {order_id} {amount_cents} {--operator=}';

    public function __construct(private RefundOrder $useCase)
    {
        parent::__construct();
    }

    public function handle(): int
    {
        $operatorId = $this->option('operator')
            ?? throw new \RuntimeException('--operator is required');

        $actor = CliActor::fromOperatorId($operatorId);

        $this->useCase->execute(
            actor: $actor,
            orderId: $this->argument('order_id'),
            amountCents: (int) $this->argument('amount_cents'),
        );

        $this->info("Refunded {$this->argument('order_id')}");
        return self::SUCCESS;
    }
}

CliActor::fromOperatorId() looks the operator up in the user table and returns an Actor with their real roles, or it throws. If the operator isn't a manager, RefundOrder::execute() will throw NotAuthorized before the order is touched. The hole closes by construction.

Queue jobs follow the same shape: serialize the actor into the job payload (id + roles, not the whole user; keep it small and verify on rehydrate), build an Actor on the worker side, hand it to the use case. Webhook handlers verify the provider signature, then call the use case with Actor::system('stripe-webhook'), and the port enforces what system can do.

Two questions you should expect

"Doesn't this duplicate Laravel's middleware?" No. Middleware handles transport: rate limiting, CSRF, login state. It does not handle operation rules like "is this user allowed to refund this specific order over this specific amount." Keep middleware for transport, use cases for operations. They don't fight.

"What about Form Requests / DTOs that authorize?" Laravel's FormRequest::authorize() and similar Symfony patterns are still HTTP-only. The CLI doesn't run FormRequest. The queue worker doesn't run it. The webhook handler doesn't run it. They are HTTP-layer ergonomics, not authorization homes. Use them for transport-level input validation; keep the rule in the use case.

What you keep, what you drop

Keep:

One AuthorizationPort interface per application, in the domain layer.
Concrete LaravelPolicyAuthorization or SymfonyVoterAuthorization adapters that bind the framework's existing policy code to that port.
An Actor value object every entry point knows how to construct.
Every use case that mutates state calls $auth->authorize(...) early, before any I/O.
A test per use case that asserts NotAuthorized is thrown for a non-privileged actor.

Drop:

$this->authorize(...) calls inside controllers.
#[IsGranted] attributes on controller methods, when the use case behind them is reachable from any non-HTTP path.
The unspoken assumption that "internal" callers (CLI, queue, webhook) are trusted because they're internal. Internal callers ship authorization regressions to production. They get caught last.

The rule lives next to the operation it gates. That keeps it fresh the moment a second entry point arrives.

If this was useful

The same shape (port in the domain, adapter at the edge, use case in the middle) handles transactions, observability, error translation, and the rest of the patterns that fail the day a second caller turns up. Decoupled PHP walks the full layout for Laravel 11 and Symfony 7 services, with migrations from framework-coupled code to a domain that outlives the framework.

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

Where Input Validation Lives: Controllers, Use Cases, or Domain?

Gabriel Anhaia — Tue, 19 May 2026 19:49:48 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: System Design Pocket Guide: Fundamentals
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Open any architecture thread on PHP Twitter and someone will tell you validation belongs in the controller. The next reply says it belongs in the form request. The third says only the domain can be trusted. The fourth quotes a book and tells everyone to use value objects. By the bottom of the thread, you still don't know where to put the code that checks whether quantity is greater than zero.

The argument is unwinnable in the abstract because everyone is right about a different thing. There are three different jobs called "validation," and they sit in three different places. When a controller tries to do all three it turns into a god object, and when a domain tries to do all three it ends up returning HTTP status codes from inside an entity. Both shapes happen in real codebases. Both are avoidable once you name the three jobs separately.

This post names them, places them, and shows what each one looks like in PHP 8.3 with Laravel 11 and Symfony 7.

The three kinds of validation

The mistake is treating "validation" as one concern. It is three.

Shape validation asks: did the request contain the fields I need, in the types I expect? Is quantity an integer? Is email a string that looks like an email? Is currency one of the three letters in the enum? This is the boundary between the outside world and your code. If shape is wrong, no further work is possible, because the use case cannot run without something well-typed to pass to it.

Business validation asks: given a well-typed request, is this operation allowed right now? It looks at the state of the system. The customer might not exist, their account might be frozen, they might be short on credit, or the product might be discontinued. This needs to query repositories, check permissions, look at the clock. It cannot run at the HTTP boundary because the HTTP boundary doesn't have a database connection, and shouldn't.

Invariant enforcement asks: can this domain object exist in this state at all? Can an Order have zero items? Can Money have a negative amount? Can a Discount exceed 100 percent? This is the constructor of the type saying "no, that combination of fields is incoherent, the type itself refuses to be constructed that way." It runs in the constructor, so a fixture, a migration, or a Tinker session can't skip it.

The three jobs map onto the three layers of a Clean / Hexagonal PHP application:

Job	Lives in	Knows about	Fails with
Shape	Controller / FormRequest / `#[Assert]`	HTTP, JSON, form fields	`422 Unprocessable Entity`
Business	Use case / application service	Repositories, clock, policies	Domain exceptions → mapped to `409`, `403`, `404`
Invariant	Domain entity / value object constructor	Nothing outside the domain	`\DomainException` / `\InvalidArgumentException`

Shape lives in the controller — Laravel 11

Laravel's FormRequest is built for this exact job. It runs before the controller method is called, fails the request with a 422 if the shape is wrong, and hands the controller a well-typed bag of data.

<?php

declare(strict_types=1);

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

final class PlaceOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'customer_id'         => ['required', 'uuid'],
            'currency'            => ['required', Rule::in(['EUR', 'USD', 'GBP'])],
            'items'               => ['required', 'array', 'min:1', 'max:100'],
            'items.*.sku'         => ['required', 'string', 'max:64'],
            'items.*.quantity'    => ['required', 'integer', 'min:1', 'max:999'],
            'items.*.price_cents' => ['required', 'integer', 'min:1'],
        ];
    }

    public function authorize(): bool
    {
        return true;
    }
}

Every rule above is a fact about the request. None of them needs a database. None of them needs to know whether the customer exists, whether the SKU is in the catalog, or whether the currency matches the customer's account. Those are different questions for a different layer.

The controller stays thin. It pulls the validated payload, maps it to a use case input DTO, and delegates:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Application\PlaceOrder\PlaceOrderInput;
use App\Application\PlaceOrder\PlaceOrderUseCase;
use App\Application\PlaceOrder\Exceptions\CustomerNotActive;
use App\Application\PlaceOrder\Exceptions\UnknownSku;
use App\Http\Requests\PlaceOrderRequest;
use Illuminate\Http\JsonResponse;

final readonly class PlaceOrderController
{
    public function __construct(
        private PlaceOrderUseCase $useCase,
    ) {}

    public function __invoke(PlaceOrderRequest $request): JsonResponse
    {
        $input = PlaceOrderInput::fromArray($request->validated());

        try {
            $order = ($this->useCase)($input);
        } catch (CustomerNotActive $e) {
            return new JsonResponse(['error' => $e->getMessage()], 403);
        } catch (UnknownSku $e) {
            return new JsonResponse(['error' => $e->getMessage()], 404);
        }

        return new JsonResponse(['order_id' => $order->id], 201);
    }
}

Notice the controller catches application exceptions, not domain ones. That is on purpose: domain exceptions should never escape the use case. If a \DomainException reaches the HTTP layer, the use case forgot to translate it, and the response is a 500. Which is correct. An unenforced invariant reaching the edge is a bug, not a user error.

Shape lives in the controller — Symfony 7

Symfony's preferred shape-validation tool in 2026 is attribute-driven #[Assert] on a DTO, paired with the MapRequestPayload argument resolver. The runtime hydrates the DTO from the request body, runs the constraints, and short-circuits with a 422 if anything fails. The controller never sees a malformed request.

<?php

declare(strict_types=1);

namespace App\Http\Dto;

use Symfony\Component\Validator\Constraints as Assert;

final readonly class PlaceOrderPayload
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Uuid]
        public string $customerId,

        #[Assert\NotBlank]
        #[Assert\Choice(['EUR', 'USD', 'GBP'])]
        public string $currency,

        #[Assert\Count(min: 1, max: 100)]
        #[Assert\Valid]
        public array $items,
    ) {}
}

final readonly class PlaceOrderItem
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Length(max: 64)]
        public string $sku,

        #[Assert\Positive]
        #[Assert\LessThanOrEqual(999)]
        public int $quantity,

        #[Assert\Positive]
        public int $priceCents,
    ) {}
}

<?php

declare(strict_types=1);

namespace App\Http\Controller;

use App\Application\PlaceOrder\PlaceOrderUseCase;
use App\Http\Dto\PlaceOrderPayload;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
use Symfony\Component\Routing\Attribute\Route;

final readonly class PlaceOrderController
{
    public function __construct(
        private PlaceOrderUseCase $useCase,
    ) {}

    #[Route('/orders', methods: ['POST'])]
    public function __invoke(
        #[MapRequestPayload] PlaceOrderPayload $payload,
    ): JsonResponse {
        $order = ($this->useCase)($payload->toInput());

        return new JsonResponse(
            ['order_id' => $order->id],
            201,
        );
    }
}

The two frameworks express the same idea with different syntax. The shape check runs before the controller body, the controller delegates to a use case, and there is no business logic at the HTTP boundary or HTTP concern leaking into the use case.

Business validation lives in the use case

The use case is where shape-valid input meets the real state of the system. It checks the things a static schema cannot know: does this customer exist, is their account active, is the SKU still in the catalog, is the requested price still current, does the user have permission for this product line.

<?php

declare(strict_types=1);

namespace App\Application\PlaceOrder;

use App\Application\PlaceOrder\Exceptions\CustomerNotActive;
use App\Application\PlaceOrder\Exceptions\UnknownSku;
use App\Domain\Customer\CustomerRepository;
use App\Domain\Order\Item;
use App\Domain\Order\Money;
use App\Domain\Order\Order;
use App\Domain\Order\OrderRepository;
use App\Domain\Pricing\PriceCatalog;
use App\Support\Clock;

final readonly class PlaceOrderUseCase
{
    public function __construct(
        private CustomerRepository $customers,
        private PriceCatalog $catalog,
        private OrderRepository $orders,
        private Clock $clock,
    ) {}

    public function __invoke(PlaceOrderInput $input): Order
    {
        $customer = $this->customers->find($input->customerId);

        if ($customer === null || !$customer->isActive()) {
            throw new CustomerNotActive($input->customerId);
        }

        $items = [];
        foreach ($input->items as $line) {
            $price = $this->catalog->priceFor($line->sku, $input->currency);
            if ($price === null) {
                throw new UnknownSku($line->sku);
            }
            $items[] = new Item(
                sku:      $line->sku,
                quantity: $line->quantity,
                price:    $price,
            );
        }

        $order = Order::place(
            customer: $customer,
            items:    $items,
            placedAt: $this->clock->now(),
        );

        $this->orders->save($order);
        return $order;
    }
}

A few things to notice. The use case has no idea what HTTP is. It accepts an input DTO and returns a domain object, so you can call it from a queue worker, a CLI command, or a unit test with no framework loaded. The failures it raises are application exceptions with named types like CustomerNotActive and UnknownSku, not generic strings, which lets the controller map each named type to an HTTP status without anyone parsing exception messages to decide on 403 vs 404. And the use case never builds a domain object from raw scalars without going through the domain's own factory (Order::place). The domain has the last word on whether the object can exist.

Invariant enforcement lives in the domain

The domain's job is to refuse to exist in an incoherent state. If Money cannot be negative, the Money constructor throws. If an Order cannot have zero items, the Order::place factory throws. The rule is the same for every type: invariants are checked at construction and at every state transition that could violate them.

<?php

declare(strict_types=1);

namespace App\Domain\Order;

use DomainException;

final readonly class Money
{
    public function __construct(
        public int $amountCents,
        public string $currency,
    ) {
        if ($amountCents < 0) {
            throw new DomainException('Money cannot be negative');
        }
        if (!in_array($currency, ['EUR', 'USD', 'GBP'], true)) {
            throw new DomainException("Unknown currency: {$currency}");
        }
    }

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

<?php

declare(strict_types=1);

namespace App\Domain\Order;

use App\Domain\Customer\Customer;
use DateTimeImmutable;
use DomainException;
use Ramsey\Uuid\Uuid;

final class Order
{
    private function __construct(
        public readonly string $id,
        public readonly string $customerId,
        public readonly array $items,
        public readonly Money $total,
        public readonly DateTimeImmutable $placedAt,
    ) {}

    public static function place(
        Customer $customer,
        array $items,
        DateTimeImmutable $placedAt,
    ): self {
        if ($items === []) {
            throw new DomainException('Order must have at least one item');
        }

        $currency = $items[0]->price->currency;
        $total = new Money(0, $currency);
        foreach ($items as $item) {
            if ($item->price->currency !== $currency) {
                throw new DomainException('All items must share a currency');
            }
            $total = $total->add(
                new Money(
                    $item->price->amountCents * $item->quantity,
                    $currency,
                ),
            );
        }

        return new self(
            id:         Uuid::uuid4()->toString(),
            customerId: $customer->id,
            items:      $items,
            total:      $total,
            placedAt:   $placedAt,
        );
    }
}

The invariants are short and absolute: at least one item, single currency across the order, non-negative money. They are the same whether the order arrived through HTTP, a queue, or a CLI. The domain does not care.

"Doesn't this double up with shape validation? The FormRequest already checks min:1 on items." It does, and it should. The FormRequest is the polite door, giving the caller a 422 with a helpful message instead of a 500. The domain is the locked vault that assumes the door was kicked in. Both are needed, because the domain might be reached by code paths that didn't pass through the door (a fixture, a Tinker session, a migration script, a queue consumer reading legacy events).

"Should I throw DomainException or use a Result type?" Either. The book treats \DomainException as the default because it composes naturally with PHP's exception machinery and stack traces, and because shipping a Result library adds a dependency without much return for most teams. Result types are great when invariant failures are routine, though if your invariant fails routinely, the rule is wrong, not the mechanism.

The decision table

When you're staring at a new validation rule and don't know where to put it, ask one question: what does this rule depend on?

The rule needs...	It lives in...	Example
Only the shape of the request	Controller / FormRequest / `#[Assert]`	`quantity` is a positive integer
The current state of the system (DB, clock, config)	Use case	Customer must be active
Nothing outside the domain itself	Domain entity / value object constructor	An order must have at least one item

Notice the failure mode of putting a rule in the wrong layer:

Business rule in the controller: the controller now reaches into the repository, runs queries, knows about domain types. Every queue worker and CLI command has to re-implement the rule because they don't go through the controller.
Invariant in the use case: a different use case (or a fixture, or a migration) constructs the same domain object without the check and produces a corrupt entity. Two months later, a report breaks because half the orders in production have a zero total.
Shape check in the domain: the domain now knows about HTTP-shaped strings, the constructor throws on user typos, and the 500 page on your site is full of Money: amount must be string of digits.

The pattern is symmetric: each layer owns one question, and can answer it without consulting the others. The result is code that survives a framework migration, because shape moves with the framework, business stays with the application, and invariants stay with the domain. Three independent moving parts instead of one tangled one.

What about value objects at the boundary?

A reasonable variant: parse the request straight into value objects in the controller, so by the time the use case is called, Sku, Quantity, Currency, and Money are already domain types. The shape check becomes "can I construct the value object from this string?" and the invariant check moves up into the constructor.

It works, and it removes one mapping step. The cost is that the controller now imports the domain types, which crosses a layer boundary some teams want to keep clean. The book treats this as a taste call: small services with a handful of types lean into it, larger services with many entry points keep the DTO-in-the-middle so the HTTP layer stays free of domain imports. Either is defensible; what is not defensible is mixing both styles in the same codebase and forgetting which controllers use which convention.

If a rule could be enforced at every layer, that is defense in depth. The shape check at the edge gives users a polite error, the invariant in the domain catches the code path that bypassed the edge, and the use case sits in the middle and asks the questions only the application can answer.

Where validation lives is not a holy war. It is a function of what the rule depends on. Once you can name the dependency, the layer picks itself.

If this was useful

This is one of the decisions the book walks through end-to-end — three layers, real PHP 8.3, Laravel and Symfony side by side, with the failure modes of getting each layer wrong. If you want the full picture of writing PHP that survives the framework underneath it, that is what Decoupled PHP is.

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

Filament + Hexagonal: Building an Admin Panel Without Coupling Your Domain

Gabriel Anhaia — Tue, 19 May 2026 19:49:10 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

You bought into hexagonal a year ago. Your Order is a plain PHP class. It doesn't extend Model. It has invariants, value objects, a refund() method that emits a domain event. The HTTP controllers are adapters. The repository is an interface in your domain layer, implemented by a Doctrine-or-Eloquent adapter on the outside.

Then ops asks for an admin panel. They want filters, bulk actions, a CSV export, audit logs, a button labelled "Refund". You look at Filament. It's the right tool. You scaffold a resource. You read the docs.

Every Filament tutorial opens the same way:

protected static ?string $model = Order::class;

$model must be an Eloquent model. Filament Resources are built on top of Eloquent's query builder, Eloquent's relationships, Eloquent's casts. The whole admin panel (tables, forms, filters, soft deletes, eager loading) assumes your domain object inherits from Illuminate\Database\Eloquent\Model.

Your domain object doesn't. That's the whole point.

What you actually need: a way to point Filament at a read-shaped Eloquent model that has nothing to do with your domain, while keeping every mutation routed through your use cases.

The shape of the answer

Order lives in App\Domain\Order. Pure PHP. Doesn't know Eloquent exists. Has methods like refund(), cancel(), markAsShipped() that enforce invariants and return events.
OrderProjection lives in App\Filament\Projections. Extends Model. Maps to the same table (or to a denormalised read table). Has no business methods. It exists so Filament can render rows fast.

The rule: Filament Resources read through OrderProjection. Mutations never write through OrderProjection. Every "Refund" or "Cancel" click in the admin panel dispatches a use case that loads the Order aggregate, calls its method, and persists through the domain's repository port.

The projection is a view. The aggregate is the source of truth. They might share a table; they might not. Either way, the projection is read-only as far as the admin is concerned.

The read projection

Start with the Eloquent model Filament will use. It's small. It exists for the admin and nothing else.

<?php

declare(strict_types=1);

namespace App\Filament\Projections;

use Illuminate\Database\Eloquent\Casts\AsArrayObject;
use Illuminate\Database\Eloquent\Model;

class OrderProjection extends Model
{
    protected $table = 'orders';

    protected $guarded = [];

    public $timestamps = false;

    protected $casts = [
        'total_cents' => 'integer',
        'items' => AsArrayObject::class,
        'status' => OrderStatus::class,
        'placed_at' => 'datetime',
        'refunded_at' => 'datetime',
    ];

    public function scopeRefundable($query)
    {
        return $query->whereIn('status', [
            OrderStatus::Paid,
            OrderStatus::Shipped,
        ]);
    }
}

$guarded = [] is safe here because the projection is never used as a mass-assignment target. Filament never writes to it. The only thing that writes to this table is the domain's repository implementation, and that goes through your aggregate.

OrderStatus is the same PHP 8.1 enum your domain uses. Cast at the projection layer; the domain consumes the same type. No translation layer for enums that are already plain values.

The scopeRefundable query scope is an admin concern, not a domain rule. The domain knows whether an order can be refunded by examining its state. The admin needs a fast SQL filter to render only refundable rows. Both can be true. The projection holds the SQL; the aggregate holds the invariant.

The Filament Resource

Wire the resource against the projection. Standard Filament, nothing exotic.

<?php

declare(strict_types=1);

namespace App\Filament\Resources;

use App\Domain\Order\OrderStatus;
use App\Filament\Projections\OrderProjection;
use App\Filament\Resources\OrderResource\Pages;
use Filament\Forms;
use Filament\Resources\Resource;
use Filament\Tables;
use Filament\Tables\Table;

class OrderResource extends Resource
{
    protected static ?string $model = OrderProjection::class;

    protected static ?string $navigationIcon = 'heroicon-o-shopping-bag';

    protected static ?string $modelLabel = 'Order';

    public static function table(Table $table): Table
    {
        return $table
            ->columns([
                Tables\Columns\TextColumn::make('id')
                    ->label('Order')
                    ->copyable(),
                Tables\Columns\TextColumn::make('customer_id')
                    ->searchable(),
                Tables\Columns\TextColumn::make('total_cents')
                    ->money('EUR', divideBy: 100)
                    ->sortable(),
                Tables\Columns\TextColumn::make('status')
                    ->badge(),
                Tables\Columns\TextColumn::make('placed_at')
                    ->dateTime()
                    ->sortable(),
            ])
            ->filters([
                Tables\Filters\SelectFilter::make('status')
                    ->options(OrderStatus::class),
            ])
            ->actions([
                Tables\Actions\ViewAction::make(),
                RefundOrderAction::make(),
            ])
            ->defaultSort('placed_at', 'desc');
    }

    public static function form(Forms\Form $form): Forms\Form
    {
        return $form->schema([]);
    }

    public static function getPages(): array
    {
        return [
            'index' => Pages\ListOrders::route('/'),
            'view' => Pages\ViewOrder::route('/{record}'),
        ];
    }
}

No EditAction. No CreateAction. No DeleteAction. The admin doesn't create or mutate orders through Filament's default CRUD path. If an operator needs to refund, they click a custom action that routes through a use case. If they need to view, they get a read-only page. That's the whole interaction surface.

This is the part most teams skip. They scaffold the resource, leave EditAction in, and within a week someone on ops has edited total_cents directly through the admin to "fix" a bug. The invariant your aggregate guarded just got bypassed. No domain event was emitted because nobody wrote one. Accounting reconciles wrong the next morning.

Take the edit and create actions out. PHP's linter won't tell you they're missing. You have to be deliberate.

The custom action that dispatches a use case

Here's the part that makes the wiring honest. A Filament action that looks like every other action, but underneath, it calls into your domain.

<?php

declare(strict_types=1);

namespace App\Filament\Resources;

use App\Application\RefundOrder\RefundOrderInput;
use App\Application\RefundOrder\RefundOrderUseCase;
use App\Domain\Order\OrderId;
use App\Filament\Projections\OrderProjection;
use Filament\Forms;
use Filament\Notifications\Notification;
use Filament\Tables\Actions\Action;

class RefundOrderAction extends Action
{
    public static function getDefaultName(): ?string
    {
        return 'refund';
    }

    protected function setUp(): void
    {
        parent::setUp();

        $this->label('Refund')
            ->icon('heroicon-o-arrow-uturn-left')
            ->color('danger')
            ->requiresConfirmation()
            ->modalHeading('Refund this order')
            ->visible(fn (OrderProjection $record): bool => in_array(
                $record->status->value,
                ['paid', 'shipped'],
                true,
            ))
            ->form([
                Forms\Components\Textarea::make('reason')
                    ->required()
                    ->minLength(10)
                    ->maxLength(500),
            ])
            ->action(function (
                OrderProjection $record,
                array $data,
                RefundOrderUseCase $useCase,
            ): void {
                $result = $useCase->execute(new RefundOrderInput(
                    orderId: new OrderId($record->id),
                    reason: $data['reason'],
                    issuedBy: auth()->user()->email,
                ));

                Notification::make()
                    ->title('Refund issued')
                    ->body("Refund {$result->refundId->value} created.")
                    ->success()
                    ->send();
            });
    }
}

The action's visible() closure reads from the projection. That's a UI concern — "should this button show up in the table" — and the projection's columns are the fastest way to answer it. The hard rule about whether a refund is allowed still lives in the aggregate; this is just whether to render the button.

The action() callback takes RefundOrderUseCase as a parameter. Laravel's container resolves it. The use case knows nothing about Filament, nothing about HTTP, nothing about the projection. It receives a plain DTO (RefundOrderInput), loads the domain Order via the repository port, calls $order->refund($reason), persists, and returns a plain DTO with the refund ID. The admin button and a queued job and a REST endpoint can all call it the same way.

The notification reads from the use case's output, not from the projection. The projection is stale at this point: the row in the table still says paid because the page hasn't re-fetched yet. The use case's return value is fresh. Trust the use case. Filament will refresh the row on the next render.

The use case, briefly

For completeness, here is what the use case looks like. It's the part of the diagram that doesn't know Filament exists.

<?php

declare(strict_types=1);

namespace App\Application\RefundOrder;

use App\Domain\Order\OrderRepository;
use App\Domain\Order\RefundReason;
use App\Domain\Shared\Clock;
use App\Domain\Shared\EventBus;

final readonly class RefundOrderUseCase
{
    public function __construct(
        private OrderRepository $orders,
        private EventBus $events,
        private Clock $clock,
    ) {
    }

    public function execute(RefundOrderInput $input): RefundOrderOutput
    {
        $order = $this->orders->byId($input->orderId);

        $refund = $order->refund(
            new RefundReason($input->reason),
            $input->issuedBy,
            $this->clock->now(),
        );

        $this->orders->save($order);

        foreach ($order->pullEvents() as $event) {
            $this->events->publish($event);
        }

        return new RefundOrderOutput(refundId: $refund->id);
    }
}

OrderRepository, EventBus, and Clock are interfaces in App\Domain. Their implementations sit in App\Infrastructure and App\Adapters. Filament is one of several adapters that consume this use case. The dependency graph points inward; nothing in the domain ever points out at Laravel or Filament.

When the read table and the write table diverge

The example above shares one table between the projection and the aggregate. That works while the admin's data needs match the domain's storage. It stops working when:

The admin wants joined customer data on every row and your domain stores customer IDs only.
The admin wants aggregated totals (last 30 days of refunds per customer) that don't fit on the orders row.
Your domain switches from a SQL repository to an event-sourced one and orders becomes a stream, not a table.

The fix is to make OrderProjection map to a separate denormalised read table (order_projections or orders_admin) populated by a listener on your domain events. When OrderRefunded fires, a projector handler updates the read row. Filament reads from order_projections. The aggregate stays clean and the admin stays fast. The admin's table can grow new columns without ever touching the domain.

The projection table is allowed to be eventually consistent. The admin is allowed to show a row that is two seconds behind the actual aggregate state. What is not allowed is for the admin to mutate the projection table directly. Every change still goes through a use case.

What this buys you

Filament still ships your admin panel in a week. Filters, exports, audit logs, role-based access, all of it. No bespoke admin written from scratch in Vue. At the same time, the Order aggregate stays pure PHP, the refund rule still lives in one place, the domain event still fires, and the use case is still testable without a database. The next framework migration (Laravel 13, Symfony, whatever) touches the adapters, not the core.

The audit trail survives intact too. Every mutation that hits the system goes through a use case, every use case publishes events, and the admin panel is a caller rather than a back door. When ops refunds an order at 3am, the trace is identical to the one a customer self-service refund leaves: same use case, different issuedBy.

That is the entire pattern. Pin those two arrows in place and Filament becomes one more adapter at the edge of your hexagon, instead of the framework that swallowed your domain.

If this was useful

This is one of the patterns from Decoupled PHP. The book walks the same shape from a single use case up to a multi-adapter production service: HTTP, CLI, queues, an admin panel, all sitting outside a framework-free domain. It is honest about where ceremony pays off and where it doesn't, and it covers the migration path for legacy Laravel and Symfony codebases that need to move incrementally without a freeze week.

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

Symfony DependencyInjection for Hexagonal: Autowiring the Whole Domain

Gabriel Anhaia — Tue, 19 May 2026 19:48:46 +0000

Book: Decoupled PHP — Clean and Hexagonal Architecture for Applications That Outlive the Framework
Also by me: Hexagonal Architecture in Go
My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
Me: xgabriel.com | GitHub

Open any hexagonal-architecture tutorial written before 2018 and you will find an appendix that nobody enjoys: the XML container config. Two screens of <service id="..."> for a project that has six classes. The complaint that killed hexagonal for a lot of Symfony shops was never about ports or adapters. It was about that file.

Modern Symfony fixed it years ago and most teams never went back to update their mental model. Autowiring plus autoconfigure plus a small bind block reduce services.yaml to under twenty lines for an entire bounded context. Your OrderRepository interface lives in App\Order\Domain\Port and its Doctrine implementation lives in App\Order\Infrastructure\Persistence. The container connects them without you naming either.

Three knobs in services.yaml do most of the work. One attribute handles the ambiguous case. The rest of the post is which knob is which and where the rule breaks.

The starting layout

Take a single bounded context, kept in one tree under src/Order/:

src/Order/
├── Domain/
│   ├── Order.php
│   ├── OrderId.php
│   └── Port/
│       ├── OrderRepository.php
│       ├── Clock.php
│       └── EventBus.php
├── Application/
│   └── UseCase/
│       ├── PlaceOrder.php
│       └── CancelOrder.php
└── Infrastructure/
    ├── Persistence/
    │   ├── DoctrineOrderRepository.php
    │   └── InMemoryOrderRepository.php
    ├── Clock/
    │   └── SystemClock.php
    ├── EventBus/
    │   ├── SymfonyMessengerEventBus.php
    │   └── NullEventBus.php
    └── Http/
        └── PlaceOrderController.php

The Domain layer depends on nothing in Infrastructure. The Application layer depends on Domain. Infrastructure depends on both and on the framework. PHP 8.3 attribute syntax across the board.

A port looks like this:

<?php

declare(strict_types=1);

namespace App\Order\Domain\Port;

use App\Order\Domain\Order;
use App\Order\Domain\OrderId;

interface OrderRepository
{
    public function save(Order $order): void;

    public function findById(OrderId $id): ?Order;
}

A use case consumes ports:

<?php

declare(strict_types=1);

namespace App\Order\Application\UseCase;

use App\Order\Domain\Order;
use App\Order\Domain\Port\Clock;
use App\Order\Domain\Port\EventBus;
use App\Order\Domain\Port\OrderRepository;

final readonly class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private Clock $clock,
        private EventBus $events,
    ) {}

    public function __invoke(PlaceOrderInput $in): OrderId
    {
        $order = Order::place(
            customerId: $in->customerId,
            items: $in->items,
            placedAt: $this->clock->now(),
        );

        $this->orders->save($order);
        $this->events->publish(...$order->pullEvents());

        return $order->id();
    }
}

Nothing in PlaceOrder knows that OrderRepository will turn out to be Doctrine, that Clock will be the system clock, or that EventBus will be Messenger. The constructor asks for interfaces. The container's job is to hand back the right concrete classes when the controller resolves PlaceOrder.

The three knobs in services.yaml

Everything in this section sits in config/services.yaml. A fresh Symfony project ships with a sensible default. Here is the version that gives you a hexagonal codebase for almost nothing:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false

    App\:
        resource: '../src/'
        exclude:
            - '../src/Kernel.php'
            - '../src/**/Domain/**/{Order,OrderId,Money}.php'
            - '../src/**/Domain/Port/**'

    App\Order\Application\UseCase\:
        resource: '../src/Order/Application/UseCase/'

    App\Order\Infrastructure\Persistence\DoctrineOrderRepository: ~
    App\Order\Domain\Port\OrderRepository:
        alias: App\Order\Infrastructure\Persistence\DoctrineOrderRepository

Four blocks, each worth a beat.

autowire: true

autowire reads the constructor signature of a service and looks up each parameter type in the container. When PlaceOrder asks for OrderRepository, Symfony searches its registry for a service whose ID is exactly that fully qualified interface name. If it finds one, it injects it. If it finds nothing, the build fails at compile time. That is the property you want.

You never write arguments: ['@app.order_repository']. The type system is the wiring spec.

autoconfigure: true

autoconfigure reads attributes and interfaces on each class and tags it accordingly. The cases that matter for a hexagonal app:

A class implementing Symfony\Component\Messenger\Handler\MessageHandlerInterface gets tagged for the message bus.
A class with #[AsCommand] gets registered as a console command.
A class with #[AsController] gets routed.
A class with #[AsMessageHandler] gets wired to the right transport.

Your inbound adapters self-register based on what they say they are. No tags: list in YAML.

The PSR-4 import block (`App\: resource: '../src/'`)

This is the line that registers your whole codebase as services. Symfony walks src/, treats every class it finds as a service candidate, and uses its fully qualified class name as the service ID. That is why OrderRepository can resolve to DoctrineOrderRepository by alias: both already exist as service IDs.

The exclude list matters. Pure domain types like Order, OrderId, and Money must NOT be services. They are value objects and entities; they get constructed by your code, not by the container. Excluding Domain/Port/** is also worth doing: interfaces alone are not services, and trying to autoregister them generates noise.

The alias

App\Order\Domain\Port\OrderRepository:
    alias: App\Order\Infrastructure\Persistence\DoctrineOrderRepository

This is the entire hex wiring, expressed in two lines per port. "When something asks for the interface, give it this implementation." Aliases compile away. There is no indirection cost at runtime.

You repeat this pattern once per port. Three ports, three aliases. That is the entire integration layer between your domain and your framework.

Two implementations, one port: the ambiguity case

The pattern above works as long as exactly one class implements each interface. Reality intrudes on day two, when you add InMemoryOrderRepository for tests:

<?php

declare(strict_types=1);

namespace App\Order\Infrastructure\Persistence;

use App\Order\Domain\Order;
use App\Order\Domain\OrderId;
use App\Order\Domain\Port\OrderRepository;

final class InMemoryOrderRepository implements OrderRepository
{
    /** @var array<string, Order> */
    private array $orders = [];

    public function save(Order $order): void
    {
        $this->orders[$order->id()->toString()] = $order;
    }

    public function findById(OrderId $id): ?Order
    {
        return $this->orders[$id->toString()] ?? null;
    }
}

Now two services implement OrderRepository. The alias is unambiguous (OrderRepository still points at the Doctrine one), but if anything autowires InMemoryOrderRepository directly, autoconfigure will not silently rewire the port.

The harder case is when two implementations of the same interface need to coexist in production. For example, a NullEventBus for the request-time path and a SymfonyMessengerEventBus for the async path. The #[Autowire] attribute resolves it at the consumer:

<?php

declare(strict_types=1);

namespace App\Order\Application\UseCase;

use App\Order\Domain\Order;
use App\Order\Domain\Port\Clock;
use App\Order\Domain\Port\EventBus;
use App\Order\Domain\Port\OrderRepository;
use App\Order\Infrastructure\EventBus\SymfonyMessengerEventBus;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

final readonly class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private Clock $clock,
        #[Autowire(service: SymfonyMessengerEventBus::class)]
        private EventBus $events,
    ) {}

    // __invoke unchanged
}

#[Autowire(service: ...)] overrides the container's default resolution for a single parameter. The interface stays as the type hint, so the domain has no idea which adapter it got. The use case still mocks cleanly in unit tests because the type is still the port.

For the inverse case (different instances of the same class with different config) #[Autowire(param: 'app.feature_flag.enabled')] injects a parameter value, and #[Autowire(env: 'STRIPE_API_KEY')] injects an env variable straight into the constructor. The consumer says what it needs; the YAML stays out of it.

bind: parameters that aren't classes

Domain code sometimes wants primitives. A retry policy needs a max attempt count. A token issuer needs a secret. Those are not service IDs, and autowire cannot guess them from a type. This is where bind earns its place:

services:
    _defaults:
        autowire: true
        autoconfigure: true
        public: false
        bind:
            string $stripeApiKey: '%env(STRIPE_API_KEY)%'
            int $defaultRetryAttempts: 3
            Psr\Log\LoggerInterface $auditLogger: '@monolog.logger.audit'

Any constructor parameter named $stripeApiKey of type string now gets the env value. Any LoggerInterface $auditLogger gets the audit channel logger. These bindings cascade into the whole container, so the same parameter name means the same value everywhere. Useful, and a trap if you reuse names.

The same effect with attributes, scoped to one consumer:

public function __construct(
    #[Autowire('%env(STRIPE_API_KEY)%')]
    private readonly string $apiKey,
    #[Autowire(service: 'monolog.logger.audit')]
    private readonly LoggerInterface $log,
) {}

Bindings in YAML are the right tool when the parameter is shared across many services. The attribute is the right tool when only one use case needs it. Mixing both is fine; preferring the attribute when in doubt keeps the YAML small.

Tagged iterators: when you have N adapters of one port

A common hexagonal pattern is a port with multiple implementations, all of which run. Domain events go to logging, metrics, and an outbox. Validators apply in sequence. The port becomes a list:

interface OrderEventListener
{
    public function on(OrderPlaced $event): void;
}

Symfony's #[AutoconfigureTag] plus #[TaggedIterator] does the rest:

<?php

namespace App\Order\Domain\Port;

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag('app.order.event_listener')]
interface OrderEventListener
{
    public function on(OrderPlaced $event): void;
}

Any class implementing the interface is tagged automatically because autoconfigure: true is on. The consumer pulls the lot:

use Symfony\Component\DependencyInjection\Attribute\AutowireIterator;

final readonly class OrderEventDispatcher
{
    public function __construct(
        #[AutowireIterator('app.order.event_listener')]
        private iterable $listeners,
    ) {}

    public function dispatch(OrderPlaced $event): void
    {
        foreach ($this->listeners as $listener) {
            $listener->on($event);
        }
    }
}

No services.yaml edit when a new listener gets added. Add a class that implements the interface and it joins the iteration. That is the rule.

The one place to drop to explicit syntax

There is one case where the autowiring pipeline is worse than just writing the definition: when the same class produces two different services with different state. Two HTTP clients pointed at different base URLs. Two database connections. Two queue workers with different topics.

services:
    App\Shared\Http\InternalApiClient:
        arguments:
            $baseUrl: '%env(INTERNAL_API_URL)%'
            $timeout: 5

    App\Shared\Http\PartnerApiClient:
        class: App\Shared\Http\HttpClient
        arguments:
            $baseUrl: '%env(PARTNER_API_URL)%'
            $timeout: 30

Trying to express this with attributes ends up worse than the YAML. Take the YAML.

What this buys you

Lines of YAML in a clean Symfony hexagonal project, per bounded context:

1 _defaults block (shared).
1 PSR-4 resource block (shared).
1 use-case resource block (shared, or absorbed into the broader one).
2 lines per port (alias).

Adding a port and an adapter is two lines. Replacing a Doctrine adapter with an in-memory one for a test environment is one line in a services_test.yaml override that changes the alias target. Adding a third adapter that runs alongside the others is zero lines: the tag picks it up.

This is the version of hexagonal that scales for a Symfony team. The framework finally pays its rent: it does the wiring you would otherwise write by hand, and it gets out of the way.

When something feels hard, the rule is the same one that applies to the architecture itself: push the complication outward. Awkward attribute syntax in a use case is a smell. The use case is asking for something framework-shaped. Move the construction to a factory in Infrastructure, register the factory, return a clean object the domain understands.

If this was useful

This is one chapter's worth of the wiring work in Decoupled PHP. The rest of the book is the same level of attention applied to ports, use cases, transactions, error translation across layers, and migrating a legacy Symfony service to this shape without a freeze week. If you have ever opened a four-year-old Symfony app and felt the framework had eaten the domain, this is the book for getting it back.

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

DEV Community: Gabriel Anhaia

Named Constructors in PHP: Why Order::place() Beats new Order(...)

What the positional constructor is hiding

Three things the same class actually does

The named-constructor pattern in PHP 8.3

Why Doctrine needs reconstitute

How the call sites change

Tests get easier in a way that is hard to notice until you do it

A small rule for choosing factory names

If this was useful

The Outbox Pattern in PHP from Scratch (No Library, 80 Lines)

Why the obvious fix does not work

The table

Writing the event inside the use case transaction

The worker

Delivery semantics

Operational notes after the table grows

What you have built

If this was useful

Three Layers vs Four Layers: When the Application Layer Earns Its Keep

The two shapes, side by side

Three layers in PHP, no apologies

When the third entry point arrives

What you actually gain (and what you don't)

The decision table

A middle path: extract on the second caller, not the first

Where the application layer ends and the domain layer begins

Verdict

If this was useful

Schema Migrations vs Aggregate Evolution: Two Different Problems

What each one is

The pure schema migration

The aggregate evolution that looks like a migration

The evolution playbook in PHP

1. Domain accepts both shapes

2. Backfill that creates the new shape

3. Read-fallback for anything you missed

Failure modes, side by side

Where this lands in a hex codebase

If this was useful

Multi-Tenant Routing in Hexagonal PHP

What belongs in the domain

What belongs outside

The seam: a tenant-aware connection

The middleware: where TenantId enters the world

The repository: tenant-scoped by construction

The test that proves the seam holds

Where the strategies diverge

What you keep

If this was useful

Pagination: Does It Belong in the Domain or in the Adapter?

What the domain actually needs to say

The port speaks domain, not SQL

The adapter does the SQL — keyset pagination, base64 cursors

The in-memory fake — why this layout pays off in tests

What you keep, what you push out

If this was useful

ULID and UUID v7 in PHP: Modern IDs for Domain Entities

Why auto-increment hurts past a single service

The two formats, side by side

Generating UUID v7 with ramsey/uuid

Wrapping the ID as a value object

Persisting to Postgres

Time-sorted, by design

Swapping in ULID

When not to do this

If this was useful

DTOs vs Value Objects: When to Use Which in PHP

The one rule

The DTO: CreateOrderInput

The value object: Money

The conversion: where they meet

What goes wrong when you mix them

A decision table

The migration path when you're already mixed up

What you keep, what you drop

If this was useful

Authorization in Use Cases, Not Controllers

The framework example that teaches you the wrong place

The day a second entry point arrives

Why Doctrine needs `reconstitute`

Generating UUID v7 with `ramsey/uuid`

The DTO: `CreateOrderInput`

The value object: `Money`

The PSR-4 import block (`App\: resource: '../src/'`)