doctrine-transactions · diff
git:20261005.042befb to git:20261005.6632a97
16 added, 12 removed. Audit A to A.
---
name: doctrine-transactions
description: Handle Doctrine transactions (ORM 3 wrapInTransaction), optimistic/pessimistic locking, flush strategies, and transaction boundaries
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 Transactions (Symfony)
## Use when
- - Designing entity relations or schema evolution.
- - Improving Doctrine correctness/performance.
+ - Several writes must succeed or fail together.
+ - Two users or workers can edit the same row concurrently.
+ - Deciding where to flush and who owns the transaction boundary.
+ - Recovering after a failed flush, a constraint violation, or a lost connection.
## 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. Place the transaction boundary in the service layer, not in the controller.
+ 2. Group related changes and flush once, inside `wrapInTransaction()`.
+ 3. Pick the concurrency strategy: `#[ORM\Version]` optimistic locking for edits, `PESSIMISTIC_WRITE` for short critical sections.
+ 4. Handle `OptimisticLockException` and constraint violations explicitly.
+ 5. After a rollback, clear the EntityManager and re-fetch what you still need.
## Guardrails
- - Keep owning/inverse sides coherent.
- - Avoid destructive migration jumps in one release.
- - Eliminate accidental N+1 and over-fetching.
+ - On ORM 3, `EntityManager::transactional()` is gone: use `wrapInTransaction()`.
+ - Outside an explicit transaction each flush commits on its own, so avoid several flushes per operation.
+ - Keep transactions and pessimistic locks short; no HTTP calls or mail inside.
+ - Do not reuse entities from a failed unit of work.
## 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.
+ - Transaction boundaries with a single flush per operation.
+ - The locking strategy chosen per entity, and how conflicts reach the user.
+ - Rollback handling and the state of the EntityManager after it.
## References
- `reference.md`