nowo-tech / transaction-doctrine
Safe plain-Doctrine default for nowo-tech/transaction-contract: a one-attempt TransactionRunnerInterface that never leaves a poisoned connection (close instead of a failing rollback after a nested deadlock), the transient-failure classifier and connection repairer, and write units that replay a dead
Requires
- php: >=8.2 <8.6
- doctrine/dbal: ^3.8.2 || ^4.0
- nowo-tech/transaction-contract: ^1.0
- psr/log: ^1.0 || ^2.0 || ^3.0
Requires (Dev)
- doctrine/orm: ^3.0
- doctrine/persistence: ^3.1 || ^4.0
- friendsofphp/php-cs-fixer: ^3.0
- igor-php/igor-php: ^0.10.0
- nowo-tech/phpstan-frankenphp: ^1.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpunit/phpunit: ^10.0 || ^11.0
- rector/rector: ^2.0
- symfony/clock: ^6.4 || ^7.0 || ^8.0
- symfony/config: ^6.4 || ^7.0 || ^8.0
- symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
- symfony/event-dispatcher: ^6.4 || ^7.0 || ^8.0
- symfony/framework-bundle: ^6.4 || ^7.0 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
- symfony/messenger: ^6.4 || ^7.0 || ^8.0
- symfony/property-access: ^6.4 || ^7.0 || ^8.0
- symfony/security-core: ^6.4 || ^7.0 || ^8.0
- symfony/serializer: ^6.4 || ^7.0 || ^8.0
- symfony/translation: ^6.4 || ^7.0 || ^8.0
- symfony/twig-bundle: ^6.4 || ^7.0 || ^8.0
- symfony/yaml: ^6.4 || ^7.0 || ^8.0
- twig/twig: ^3.0
Suggests
- doctrine/orm: For DoctrineTransactionRunner::forEntityManager() and write units on entity managers
- doctrine/persistence: To reset a closed entity manager through a ManagerRegistry (required by WriteUnit)
- nowo-tech/ui-kit-bundle: The conflict page extends UiKit's error page when UiKit is installed
- psr/event-dispatcher: To dispatch WriteUnitRetryEvent before each write-unit replay (Symfony's event_dispatcher)
- symfony/clock: To pause between write-unit attempts through the Symfony clock (testable)
- symfony/http-kernel: For the optional NowoTransactionDoctrineBundle (#[AsWriteUnit], 409 conflict responder, worker hygiene)
- symfony/messenger: For WriteUnitMiddleware (replays a consumed message after a lock conflict)
- twig/twig: For the branded HTML conflict page (overridable template)
Provides
None
Conflicts
- symfony/http-kernel: <6.4
- symfony/messenger: <6.4
Replaces
None
- v1.7.1
- v1.7.0
- v1.6.1
- v1.6.0
- v1.5.0
- v1.4.0
- dev-main / 1.3.x-dev
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.0
- v1.0.0
- dev-fix/ui2-follow-ups
- dev-feat/1.7-followups
- dev-fix/1.6.1-followups
- dev-feat/request-commit-watermark
- dev-feat/conflict-codes
- dev-feat/reset-between-attempts
- dev-fix/locales-it-nl-pt
- dev-feat/kit79-write-units
- dev-chore/req-regrade-2026-11-18
- dev-fix/se-igor-baseline-docs
- dev-feat/obs-001-psr3-logging
- dev-feat/dbal3-support
- dev-fix/audit-qa-failure-semantics
This package is auto-updated.
Last update: 2026-11-19 10:15:50 UTC
README
⭐ Found this useful? Install from Packagist and give the repo a star on GitHub if it helps you.
Safe plain-Doctrine default for nowo-tech/transaction-contract:
DoctrineTransactionRunner implements TransactionRunnerInterface with one attempt and no retry, for a bundle
to use when the host wires no adapter. Since 1.3.0 also write units that replay a deadlock, lock wait timeout or
(since 1.5.0) serialization failure, and an optional Symfony bundle (#[AsWriteUnit], Messenger middleware, one lock-conflict answer 409 +
Retry-After, worker connection hygiene). doctrine/dbal required; doctrine/orm, doctrine/persistence and the
Symfony packages optional.
This bundle is FrankenPHP worker mode friendly.
Installation
composer require nowo-tech/transaction-doctrine
Supports doctrine/dbal ^3.8.2 || ^4.0; the entity manager variant works with ORM 2.20+ and 3.x. Details:
Installation.
Usage
use Nowo\TransactionDoctrine\DoctrineTransactionRunner; // The bundle's own entity manager (may be cleared or reset after a failure) $runner = DoctrineTransactionRunner::forEntityManager($ownManager, $managerRegistry, 'my_bundle'); // The host's entity manager (1.6.0): never cleared or reset while open, replaced only when closed $runner = DoctrineTransactionRunner::forHostEntityManager($entityManager, $managerRegistry, 'default'); $runner->run(fn () => $orders->get($id)->pay($amount)); // begin, run, flush, commit
After any failure it leaves neither a poisoned connection nor pending changes: the levels it opened are rolled
back to the entry level (the connection is closed only when that rollback fails), and the entity manager has no
pending changes from the failed operation, with a shared, host-owned manager disturbed only as much as that requires.
Transient failures (deadlocks, lock waits, serialization failures) become TransientStorageFailure; anything else is
rethrown unchanged. The full behaviour reference (failure table, nested runs, DBAL 3 emulated nesting, wiring) is in
Usage.
Also exported: TransientFailureClassifier, TransientFailureKind, ConnectionRepairer (the same logic as
nowo-tech/doctrine-deadlock-retry-bundle 3.0).
Write units and the 409 lock-conflict answer (1.3.0)
// Programmatic: replayed up to 3 times (full jitter) after a deadlock, lock wait timeout or serialization failure, outermost unit only. $writeUnit->run(fn (int $attempt) => $runner->run(fn () => $tasks->get($id)->moveTo($column)));
#[AsWriteUnit] // controller: replayed with freshly resolved arguments public function move(Task $task): Response { /* ... */ }
With NowoTransactionDoctrineBundle registered, a write unit that still conflicts answers 409 (or 503 with
conflict_response.status: 503) with Retry-After: JSON {"error": "concurrency_conflict", "code": "CONFLICT_001", "message": …} or a branded Try again page (UiKit's error page when installed). When part of the unit already
committed, or anything was committed earlier in the same request (request commit watermark, 1.6.0), the code is
CONFLICT_002 and there is no Retry-After. Every answer also carries X-Conflict-Code: CONFLICT_001|CONFLICT_002
(1.6.0; clients key on it or on code, never on error) (Concurrency). Hosts and bundles map their own exceptions with
LockConflictExceptionInterface or a ConflictExceptionMapperInterface service, and shape their own answers with a
ConflictResponseFormatterInterface service, never by route name. See Usage and
Configuration.
Logging (optional)
Pass a PSR-3 logger as the last argument; the default is a NullLogger, so nothing changes when you do not:
$runner = DoctrineTransactionRunner::forHostEntityManager($entityManager, $managerRegistry, 'default', 1, $logger); // forEntityManager($ownManager, $managerRegistry, 'my_bundle', 1, $logger) takes the logger in the same place $repairer = new ConnectionRepairer(null, $logger);
| Event | Level |
|---|---|
| Operation failed, classified transient (deadlock, lock wait, ...) | notice |
| Operation failed, not transient | debug |
| Levels rolled back to the entry level | notice |
| Rollback failed, connection closed (session state lost) | warning |
| Entity manager closed and reset through the registry | notice |
| Entity manager cleared after a storage failure, no registry given | notice |
| Entity manager cleared after a domain failure | debug |
Context is structured and safe: exception class and code, nesting levels, action, manager name. SQL, parameters and exception messages are never logged. A logger that throws is ignored, and the runner stays stateless, so one instance is safe in a long-running worker.
- Do not log to the same database connection the runner uses (for example a Monolog Doctrine handler on the default connection): the line is written while that connection's transaction is failing or being rolled back, so it is lost. Log to a file, a stream or another connection.
exception_codeis the caught exception'sgetCode(): the driver / SQLSTATE code for a storage failure, but for a domain exception it is whatever your application set (often0). Do not read it as a database error code.
Documentation
- Installation
- Configuration
- Usage
- Concurrency (REQ-RUNTIME-003)
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
Additional documentation
Tests and coverage
- Tests: PHPUnit: unit tests (
tests/Unit) plus a real-database suite (tests/Integration/Database: MySQL 8.4, MariaDB 11.4, PostgreSQL 16) that runs whenTD_MYSQL_URL,TD_MARIADB_URLandTD_POSTGRES_URLare set (make test-with-db; the CI job "Real databases" runs it on DBAL 4 + ORM 3, DBAL 3 + ORM 3 and DBAL 3 + ORM 2). - PHP (lines): 100% of
src/(567/567 lines, 77/77 methods; CI gate on PHP 8.2; locallymake test-coverage). - TS/JS: N/A
- Python: N/A
License
MIT. See LICENSE.
