- What does dama/doctrine-test-bundle actually do for my test suite?
- It wraps your configured DBAL driver in a StaticDriver that keeps one database connection alive per PHP process. A PHPUnit (or Behat) extension opens a transaction before each test and rolls it back afterwards, so the schema is never rebuilt and fixtures are never reloaded. It also configures a Psr6StaticArrayCache as the metadata and query cache for all EntityManagers. The result is faster, isolated tests as long as you avoid implicit-commit DDL such as ALTER TABLE or DROP TABLE.
- How do I install and enable dama/doctrine-test-bundle for PHPUnit?
- Install it as a dev dependency with composer require --dev dama/doctrine-test-bundle. With Symfony Flex the bundle is registered automatically; otherwise add DAMADoctrineTestBundle::class to config/bundles.php under the test environment. Then register DAMA\DoctrineTestBundle\PHPUnit\PHPUnitExtension in the extensions block of your phpunit.xml. No other configuration is required for a single default connection.
- Does dama/doctrine-test-bundle work with Laravel?
- The package is published as a Symfony bundle, so it is not officially supported in Laravel and there is no Laravel service provider. Laravel applications that use Doctrine through laravel-doctrine can still benefit from the StaticDriver and the transaction-rollback logic, but you would have to wire them manually. Most Laravel teams instead use the built-in RefreshDatabase or DatabaseTransactions traits, which provide similar per-test isolation for Eloquent and the query builder.
- Why does the bundle need use_savepoints enabled with DBAL below version 4?
- Starting with version 8, the bundle relies on savepoints to nest transactions correctly when your application code opens its own transactions inside a test. DBAL 4 handles this natively, but on DBAL 3 and earlier you must set use_savepoints: true on every relevant connection in your doctrine.dbal configuration. Without it, nested transactions can behave unexpectedly and rollbacks may not restore the expected state.
- Why do my tests break after running DDL like ALTER TABLE or DROP TABLE?
- Statements that cause an implicit commit, such as ALTER TABLE, DROP TABLE, or MySQL LOAD DATA, end the transaction the bundle opened, so the rollback afterwards no longer isolates the test. This is expected behaviour rather than a bug, and the fix is to keep schema-changing DDL out of rollback-based tests. For the rare case where you need it, opt out of the rollback for that specific test instead of disabling the bundle globally.
- Can I use dama/doctrine-test-bundle with multiple database connections?
- Yes, the extension starts and rolls back a transaction on every configured DBAL connection, which covers setups like a primary and a replica. If you need finer control you can enable or disable the static driver per connection through the bundle configuration. This makes it practical for applications that talk to more than one database during a single test.
- How does Psr6StaticArrayCache improve Doctrine test performance?
- The bundle registers a static PSR-6 array cache as the metadata and query cache for all EntityManagers. Because the cache lives for the whole PHP process, Doctrine does not re-parse mapping metadata or re-run identical queries for every test that boots a kernel. This is especially noticeable in controller and container-aware tests where many kernels are created, cutting both runtime and memory usage.
- How can I inspect the database state while debugging a failing test?
- Because the transaction is rolled back by default, changes made during the test are not visible after it finishes. To inspect them, call StaticDriver::commit() inside the test or disable the rollback for that specific test case. Version 8.7 also emits a warning when a transaction was never closed, which helps surface lifecycle bugs that previously failed silently.
- Which PHPUnit and PHP versions does dama/doctrine-test-bundle support?
- Recent releases target PHP 8.1 and newer and require PHPUnit 11 through 13, so older legacy projects may need to upgrade their test tooling first. The bundle also depends on symfony/phpunit-bridge, which adds another compatibility layer to keep in mind. CI now runs against PHP 8.6, so expect the supported PHP floor to move forward over time.
- Is dama/doctrine-test-bundle still maintained, and what are the alternatives?
- Yes, the project is actively maintained, with version 8.7.0 adding Behat 4 support and an unclosed-transaction warning without any configuration changes. Alternatives include wrapping tests in transactions yourself with DBAL, rebuilding the schema per test with a tool like doctrine-fixtures plus a fast SQLite database, or using Laravel's RefreshDatabase and DatabaseTransactions traits in Laravel projects. For Symfony applications on Doctrine, this bundle remains the lowest-effort way to get rollback-based isolation.