Doctrine Entity Mapping

When to use

• The user must pick a primary key and an id generation strategy (auto, identity, sequence, or UUID) for a Doctrine entity.
• The user needs to map PHP property types to Doctrine column types, lengths, and nullability.
• The user needs to declare how a PHP class maps to a table with Doctrine — entity, columns, and identifier.

When NOT to use

• Do not use Doctrine mapping attributes on an Active Record model (for example an Eloquent model) that already maps itself by convention.
• Do not map an entity for data that is only queried read-only and never persisted, such as ad-hoc report rows.

Core guidance

• Keep large columns out of the default hydration path — For large text or BLOB columns rarely needed at read time, split them into a separate entity or use a partial/projection query, so the common load does not hydrate megabytes per row.
• Prefer PHP 8 attribute mapping over annotations — On PHP 8.1+, map entities with native attributes (#[ORM\Entity], #[ORM\Column]) rather than doc-block annotations. Reserve XML mapping for cases where mapping must live outside the class.

Quick recipe

1. Add #[ORM\Entity] (and #[ORM\Table(name: 'orders')] if the table name differs) to the class so Doctrine treats it as a mapped entity. (verify: orm:mapping:describe App\Entity\Order lists the class without a mapping error.)
2. Add an id property with #[ORM\Id], #[ORM\GeneratedValue], and #[ORM\Column] so the entity has a primary key and a generation strategy. (verify: The mapping describe output shows the id field flagged as the identifier.)
3. Map each field with #[ORM\Column(type: ..., nullable: ...)], then generate a reviewed migration from the mapping diff and apply it. (verify: The generated migration creates the table with the expected columns, types, and nullability.)

Best practices

• Persist a value object (money, email, coordinates) with an #[ORM\Embedded] embeddable or a registered custom DBAL type, rather than flattening it into loose scalar columns by hand
• Declare the identifier with #[ORM\Id], #[ORM\GeneratedValue], and choose the strategy to fit the driver — IDENTITY for MySQL auto-increment, SEQUENCE for PostgreSQL, or an application-assigned UUID when ids must be known before insert
• Set nullable: true on the column only when the PHP property type is nullable (?string), and keep them in sync — a non-nullable typed property must map to a NOT NULL column

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Mapping to datetime lets mutable DateTime corrupt change tracking — Mapping a property as the mutable datetime type with a DateTime object lets in-place mutation slip past dirty checking. Fix: Map as datetime_immutable and type the property DateTimeImmutable so every change produces a new object the unit of work can detect.
2. Entity without an — An entity class annotated #[ORM\Entity] but with no #[ORM\Id] property throws a MappingException at boot. Fix: Declare exactly one identifier property with #[ORM\Id] (or a composite of several) before using the entity.
3. Unspecified string length silently defaults to 255 — A #[ORM\Column(type: 'string')] without an explicit length generates a VARCHAR(255), truncating longer values. Fix: Set length explicitly, or map to the text type when the field has no natural bound.

Version notes

• Attributes are the only in-core annotation format on ORM 3 (PHP >=8.1) — Doctrine ORM 3 ships attribute and XML mapping in core and drops the doc-block annotation driver; on ORM 2 both attributes and annotations still work.

Security

• Do not hydrate entities directly from request input — Do not build or populate a mapped entity by copying raw request arrays field by field; map validated input onto the entity through explicit setters or a DTO, and never expose the identifier or internal flags to mass assignment.

Testing

• Activation and decision behavior are verified in eval/scenarios/doctrine/entities-mapping.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: doctrine/orm-basics
Related: doctrine/associations, doctrine/orm-basics, php/value-objects