doctrine-relations · diff
git:20261005.042befb to git:20261005.d9aebf3
17 added, 12 removed. Audit A to A.
---
name: doctrine-relations
description: Define Doctrine entity relationships (OneToMany, ManyToMany, ManyToOne); configure cascade, orphan removal, multiple entity managers; prevent N+1 queries
capabilities: [read, search, edit, shell]
tags: [doctrine]
# projected by `bun run build` — do not edit by hand
allowed-tools:
- Read
- Glob
- Grep
- Write
- Edit
- Bash
---
# Doctrine Relations (Symfony)
## Use when
- - Designing entity relations or schema evolution.
- - Improving Doctrine correctness/performance.
+ - Mapping a `ManyToOne`, `OneToMany`, `ManyToMany` or `OneToOne` and choosing the owning side.
+ - Deciding between `cascade` and `orphanRemoval` for child entities.
+ - A relation does not persist (only the inverse side was set), or `contains()` is slow on a large inverse collection.
+ - Splitting entities across several entity managers.
## Default workflow
- 1. Model ownership/cardinality and transactional boundaries.
- 2. Apply mapping/schema changes with migration safety.
- 3. Tune fetch/query behavior for hot paths.
- 4. Verify lifecycle behavior with targeted tests.
+ 1. Pick the owning side (holds the foreign key, `ManyToOne` with `inversedBy`) and the inverse side (`OneToMany` with `mappedBy`).
+ 2. Initialize collections with `ArrayCollection` in the constructor, and write `addX()` and `removeX()` helpers that keep both sides in sync.
+ 3. Use `cascade: ['persist']` for aggregates saved together, and `orphanRemoval: true` only for true composition.
+ 4. Mark large inverse collections `fetch: 'EXTRA_LAZY'`, or test membership from the owning side.
+ 5. Add fetch joins where a use case reads the relation, to avoid N+1 queries.
+ 6. With several entity managers, keep each entity set in one manager and fetch repositories through `ManagerRegistry`.
## Guardrails
- - Keep owning/inverse sides coherent.
- - Avoid destructive migration jumps in one release.
- - Eliminate accidental N+1 and over-fetching.
+ - Doctrine persists what the owning side holds: always set the `ManyToOne` reference.
+ - Avoid `cascade: ['remove']` on large collections (one DELETE per row), and never use `orphanRemoval` on shared entities.
+ - A relation cannot span two entity managers.
+ - For a non-default entity manager, fetch repositories with `ManagerRegistry::getRepository(Entity::class, 'name')`.
## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.
## Output contract
- - Entity/migration changes.
- - Integrity and performance decisions.
- - Validation outcomes and rollback notes.
+ - Entity mappings with the owning and inverse sides, cascade and orphan decisions.
+ - Fetch strategy for large collections and hot paths.
+ - Result of `doctrine:schema:validate`.
## References
- `reference.md`