标签：#doctrine

Originally posted on https://symfonycasts.com/blog/honest-entities Your Doctrine entities are lying to you! For years, the standard way to build Doctrine entities in Symfony has looked something like this (and it's still what MakerBundle generates today): #[ORM\Entity] class ConferenceTalk { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null ; #[Assert\NotBlank] #[ORM\Column(length: 255)] private ?string $title = null ; #[ORM\Column(type: Types::TEXT, nullable: true)] private ?string $abstract = null ; public function getId (): ?int { return $this -> id ; } public function getTitle (): ?string { return $this -> title ; } public function setTitle ( ?string $title ): static { $this -> title = $title ; return $this ; } public function getAbstract (): ?string { return $this -> abstract ; } public function setAbstract ( ?string $abstract ): static { $this -> abstract = $abstract ; return $this ; } } At first glance, this looks perfectly reasonable. The title field is required. We know that because it has a NotBlank constraint and the database column is not nullable. But look closer. private ?string $title = null ; public function setTitle ( ?string $title ): static public function getTitle (): ?string According to the PHP type system, the title is optional. In fact, the public API of this class explicitly allows us to set it to null . That means this is perfectly valid: $talk = new ConferenceTalk (); And so is this: $talk = new ConferenceTalk (); $talk -> setTitle ( null ); Both objects represent a conference talk that can never be successfully persisted. Eventually, Doctrine catches the problem: $talk = new ConferenceTalk (); $entityManager -> persist ( $talk ); $entityManager -> flush (); // boom! SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'title' cannot be null The database knows that a conference talk must have a title. Our PHP code does not. So why do we build entities this way? Historically, this pattern was optimized for simpli

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 cha