• 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 add a column to a table. discount_cents, nullable, default zero. A small migration, a five-minute ticket. The next morning a teammate pings you: orders placed overnight have a discount of null where the domain expected zero, and the total calculation now throws a TypeError deep inside a value object.

You trace it back. A reflection-based mapper copied the new column straight onto a property the domain class did not declare, then the next read pulled it back as null and handed it to Money. Nobody wrote the line that connected discount_cents to the domain. The mapper guessed, and the guess leaked the table's shape into a class that was supposed to know nothing about tables.

This is the case against automatic mapping at the persistence boundary. A hand-rolled mapper is more typing. It is also the seam that stops the database schema from reaching into your domain.

What the boundary is for

In a hexagonal layout the domain Order knows about line items, currencies, and the rule that an order needs at least one item. It does not know there is a orders table with a discount_cents column. The repository adapter is the only place those two worlds touch, and the mapper is the translator that stands at that seam.

A reflection or annotation-driven mapper collapses the seam. It reads the persistence shape, walks the domain object's properties, and copies whatever names line up. When the two shapes match, it feels free. When they drift, the drift travels silently across the boundary you built it to protect: a renamed column, a new field, a type that does not round-trip.

The whole point of the adapter is that the domain and the table can change on different days for different reasons. An automatic mapper ties them back together by name. You get the coupling you were trying to avoid, hidden behind a library that promises convenience.

The reflection mapper

Here is the shape of an automatic mapper. It pulls a row, instantiates the domain class without a constructor, and assigns each column to the matching property via reflection.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence;

final class ReflectionMapper
{
    public function toDomain(array $row, string $class): object
    {
        $ref = new \ReflectionClass($class);
        $object = $ref->newInstanceWithoutConstructor();

        foreach ($row as $column => $value) {
            $prop = $this->camelCase($column);
            if ($ref->hasProperty($prop)) {
                $p = $ref->getProperty($prop);
                $p->setValue($object, $value);
            }
        }

        return $object;
    }

    private function camelCase(string $s): string
    {
        return lcfirst(str_replace(
            ' ',
            '',
            ucwords(str_replace('_', ' ', $s)),
        ));
    }
}

Read what it actually does. It bypasses the constructor, so no invariant runs. It matches on a name convention, so a column rename breaks it at runtime, not at compile time. It assigns raw scalars to typed properties, so discount_cents lands on a property the domain never meant to expose, or worse, a null reaches a non-nullable Money field and explodes three calls deep.

The mapper has no idea that amount_minor plus currency are supposed to become one Money value object. It sees two columns and two properties, or it sees them missing and skips them. Either way the domain's actual rules (the ones that make Order an Order) never get a vote.

The hand-rolled mapper

Now the explicit version. Twenty lines, both directions stated by hand.

<?php

declare(strict_types=1);

namespace App\Infrastructure\Persistence;

use App\Domain\Order\Order;
use App\Domain\Order\OrderId;
use App\Domain\Customer\CustomerId;
use App\Domain\Order\OrderStatus;
use App\Domain\Shared\Money;

final class OrderMapper
{
    public function toDomain(array $row): Order
    {
        return Order::fromPersistence(
            id: new OrderId($row['id']),
            customerId: new CustomerId($row['customer_id']),
            items: $this->itemsFromJson($row['items']),
            total: new Money(
                (int) $row['total_minor'],
                $row['currency'],
            ),
            status: OrderStatus::from($row['status']),
            placedAt: new \DateTimeImmutable($row['placed_at']),
        );
    }

    public function toRow(Order $order): array
    {
        return [
            'id' => $order->id()->value,
            'customer_id' => $order->customerId()->value,
            'items' => $this->itemsToJson($order->items()),
            'total_minor' => $order->total()->amountInMinorUnits,
            'currency' => $order->total()->currency,
            'status' => $order->status()->value,
            'placed_at' => $order->placedAt()
                ->format('Y-m-d H:i:s'),
        ];
    }
}

Every line is a decision you can read in code review. total_minor and currency become one Money. status goes through the enum's from, which throws on an unknown value instead of smuggling a bad string into the domain. The constructor route is Order::fromPersistence, a named factory the domain owns, not a reflection backdoor that skips every check.

When you add discount_cents, nothing happens until you add a line for it here. The new column sits in the table, invisible to the domain, until you decide what it means and write the translation. The mapper ignores the column until you choose to map it, so a new field is a deliberate decision instead of a silent guess.

What you give up, and why it is fine

The objection is real: explicit mapping is repetitive. Two methods per entity, a line per field, and you write them by hand every time. A 40-column table is a 40-line mapper in each direction. That feels like a tax.

It is a tax you pay once and read forever. The reflection mapper saves you the forty lines today and charges you on every schema change, every column rename, every type that does not round-trip cleanly, every debugging session that starts with "why is this field null." The hand-rolled version turns all of those into a single, greppable place: OrderMapper. You know exactly where the table meets the domain, because there is one file where it happens.

There is a quieter benefit. The mapper is the document that records what the persistence shape actually is. A new engineer reads OrderMapper::toRow and learns the table layout and the domain layout and the relationship between them in one screen. No annotation soup, no reflection magic to trace through a vendor directory.

Where Doctrine fits

Doctrine sits in the middle of this argument. Its default hydrator uses newInstanceWithoutConstructor and reflection, which is the automatic approach. That is fine for an active-record style where the entity is the table. It is not fine when the entity is a domain aggregate with invariants and value objects.

The clean move is the same one the complete hexagonal service uses: map a plain OrderRecord persistence class with Doctrine annotations, let Doctrine hydrate that record automatically, and run your hand-rolled mapper between the record and the domain Order. Doctrine gets the dumb data holder it is good at. The domain gets a translator that respects its factories and value objects.

public function findById(OrderId $id): ?Order
{
    $record = $this->em->find(
        OrderRecord::class,
        $id->value,
    );

    return $record === null
        ? null
        : $this->mapper->toDomain($record);
}

Two layers of mapping, on purpose. The reflection one stays in vendor code, mapping rows to a record class whose only job is to hold data. The explicit one is yours, mapping records to a domain object whose job is to mean something. The seam between them is the line you control.

The rule of thumb

Use automatic mapping for data that is only ever data — read models, projections, DTOs you serialize and forget. The shape is the shape; there is nothing to protect.

Hand-roll the mapper at any boundary where one side is a domain aggregate. The extra lines are the price of a domain that does not learn about your table layout by accident. A schema change should be a decision you make at the seam, not a surprise that arrives in production at 3 a.m.

The next time a mapper "just works" across a schema change, ask what it did with the columns you did not mean for it to see.

If this was useful

The persistence boundary, and the discipline of keeping the domain ignorant of how it is stored, is one of the threads Decoupled PHP pulls all the way through — from value objects and aggregates to repositories, the outbox, and migrating a framework-coupled codebase one slice at a time. The goal is an application where the table can change without the domain noticing, and the framework stays an adapter rather than the protagonist.

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