Why Every PHP Use Case Should Own Exactly One Database Transaction

A common bug in PHP applications occurs when database transactions are split across multiple repository saves, leaving aggregates in a half-committed state — for example, an order header written but its line items missing. The root cause is placing flush() calls inside individual repositories, which commits data prematurely before the full use case has completed. The recommended fix is to remove flush() from repositories so they only stage changes, and instead wrap the entire use case in a single transaction boundary. Using Doctrine's wrapInTransaction() helper keeps transaction logic out of domain classes by treating it as a cross-cutting concern handled at the application layer. This pattern ensures all writes either succeed together or roll back completely, preventing inconsistent database states.