/doctrine-transactions

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

• 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. 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

• 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

• 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`