feat: deprecate ResetDatabase trait

Author: nikophil

.env

@@ -11,3 +11,6 @@ USE_DAMA_DOCTRINE_TEST_BUNDLE="0"
 USE_FOUNDRY_PHPUNIT_EXTENSION="0"
 USE_PHP_84_LAZY_OBJECTS="0"
 PHPUNIT_VERSION="12" # allowed values: 9, 10, 11, 12
+
+# Only relevant for "reset-database" testsuite
+DATABASE_RESET_MODE="schema" # allowed values: schema, migrate

.github/workflows/ci.yml

@@ -133,6 +133,7 @@ jobs:
       DATABASE_RESET_MODE: ${{ matrix.reset-database-mode == 1 && 1 || 0 }}
       MIGRATION_CONFIGURATION_FILE: ${{ matrix.migration-configuration-file == 'no' && '' || format('tests/Fixture/MigrationTests/configs/{0}.php', matrix.migration-configuration-file) }}
       PHPUNIT_VERSION: 11
+      USE_FOUNDRY_PHPUNIT_EXTENSION: 1
     services:
       postgres:
         image: ${{ contains(matrix.database, 'pgsql') && 'postgres:15' || '' }}

README.md

@@ -51,7 +51,7 @@ $ composer update
 # run main testsuite (with "schema" reset database strategy)
 $ ./phpunit
 
-# run "migrate" testsuite (with "migrate" reset database strategy)
+# run "reset-database" testsuite
 $ ./phpunit --testsuite reset-database
 ```
 
@@ -73,6 +73,7 @@ PHPUNIT_VERSION="11" # possible values: 9, 10, 11, 11.4
 
 # test reset database with migrations,
 # only relevant for "reset-database" testsuite
+DATABASE_RESET_MODE="migrate"
 MIGRATION_CONFIGURATION_FILE="tests/Fixture/MigrationTests/configs/migration-configuration.php"
 
 # run test suite with postgreSQL

UPGRADE-2.9.md

@@ -0,0 +1,53 @@
+# Migration guide from Foundry 2.8 to 2.9
+
+The main feature of Foundry 2.9 is the deprecation of the `ResetDatabase` trait, in favor of a `#[ResetDatabase]` attribute,
+along with the [PHPUnit extension](https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#phpunit-extension)
+shipped by Foundry. 
+
+The trait will be removed in Foundry 3.0, and the usage of the attribute will be mandatory to reset the database in your tests.
+
+> [!WARNING]
+> The PHPUnit extension mechanism was introduced in PHPUnit 10. This means that Foundry 3 won't be compatible 
+> with PHPUnit 9 anymore (but Foundry 2 will remain compatible with PHPUnit 9).
+
+## How to
+
+> [!IMPORTANT]
+> If you're still not using PHPUnit 10 or grater, there is nothing to do (yet!)
+
+Enable Foundry's [PHPUnit extension](https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#phpunit-extension)
+in your `phpunit.xml` file:
+
+```xml
+<phpunit>
+    <extensions>
+        <bootstrap class="Zenstruck\Foundry\PHPUnit\FoundryExtension"/>
+    </extensions>
+</phpunit>
+```
+
+And then, replace all the `use ResetDatabase;` statements by a `#[\Zenstruck\Foundry\Attribute\ResetDatabase]` attribute
+on your test classes. Note that you can put the attribute on a parent class, it will be inherited by all its children.
+
+## Rector rules
+
+A Rector set is available to automatically replace the trait by the attribute in all your tests.
+
+First, you'll need to install `rector/rector`:
+```shell
+composer require --dev rector/rector
+```
+
+Then, create a `rector.php` file:
+
+```php
+<?php
+
+use Rector\Config\RectorConfig;
+use Zenstruck\Foundry\Utils\Rector\FoundrySetList;
+
+return RectorConfig::configure()
+    ->withPaths(['tests'])
+    ->withSets([FoundrySetList::FOUNDRY_2_9])
+;
+```

docs/index.rst

@@ -1650,33 +1650,46 @@ Add Foundry's `PHPUnit Extension`_ in your `phpunit.xml` file:
 Database Reset
 ~~~~~~~~~~~~~~
 
-This library requires that your database be reset before each test. The packaged ``ResetDatabase`` trait handles
+This library requires that your database be reset before each test. The packaged ``ResetDatabase`` attribute handles
 this for you.
 
 ::
 
     use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
-    use Zenstruck\Foundry\Test\Factories;
-    use Zenstruck\Foundry\Test\ResetDatabase;
+    use Zenstruck\Foundry\Attribute\ResetDatabase;
 
+    #{ResetDatabase]
     class MyTest extends WebTestCase
     {
-        use ResetDatabase, Factories;
-
         // ...
     }
 
-Before the first test using the ``ResetDatabase`` trait, it drops (if exists) and creates the test database.
+Before the first test using the ``ResetDatabase`` attribute, it drops (if exists) and creates the test database.
 Then, by default, before each test, it resets the schema using ``doctrine:schema:drop``/``doctrine:schema:create``.
 
+.. note::
+
+    If you're still using PHPUnit 9, the database can be reset by adding the trait ``Zenstruck\Foundry\Test\ResetDatabase``::
+
+        use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+        use Zenstruck\Foundry\Test\Factories;
+        use Zenstruck\Foundry\Test\ResetDatabase;
+
+        class MyTest extends WebTestCase
+        {
+            use ResetDatabase, Factories;
+
+            // ...
+        }
+
 .. tip::
 
-    Create a base TestCase for tests using factories to avoid adding the traits to every TestCase.
+    Create a base TestCase for tests using factories to avoid adding the attribute to every TestCase.
 
 .. tip::
 
     If your tests :ref:`are not persisting <without-persisting>` the objects they create, the ``ResetDatabase``
-    trait is not required.
+    attribute is not required.
 
 By default, ``ResetDatabase`` resets the default configured connection's database and default configured object manager's
 schema. To customize the connection's and object manager's to be reset (or reset multiple connections/managers), use the
@@ -2048,7 +2061,7 @@ Global State
 
 If you have an initial database state you want for all tests, you can set this in the config of the bundle. Accepted
 values are: stories as service, "global" stories and invokable services. Global state is loaded before each test using
-the ``ResetDatabase`` trait. If you are using `DamaDoctrineTestBundle`_, it is only loaded once for the entire
+the ``ResetDatabase`` attribute. If you are using `DamaDoctrineTestBundle`_, it is only loaded once for the entire
 test suite.
 
 .. configuration-block::
@@ -2071,7 +2084,7 @@ test suite.
 
 .. note::
 
-    The :ref:`ResetDatabase <enable-foundry-in-your-testcase>` trait is required when using global state.
+    The :ref:`ResetDatabase <enable-foundry-in-your-testcase>` attribute is required when using global state.
 
 .. warning::
 
@@ -2267,7 +2280,7 @@ This library integrates seamlessly with `DAMADoctrineTestBundle <https://github.
 wrap each test in a transaction which dramatically reduces test time. This library's test suite runs 5x faster with
 this bundle enabled.
 
-Follow its documentation to install. Foundry's ``ResetDatabase`` trait detects when using the bundle and adjusts
+Follow its documentation to install. Foundry's ``ResetDatabase`` attribute detects when using the bundle and adjusts
 accordingly. Your database is still reset before running your test suite but the schema isn't reset before each test
 (just the first).
 
@@ -2383,10 +2396,10 @@ Non-Kernel Tests
 ~~~~~~~~~~~~~~~~
 
 Foundry can be used in standard PHPUnit unit tests (TestCase's that just extend ``PHPUnit\Framework\TestCase`` and not
-``Symfony\Bundle\FrameworkBundle\Test\KernelTestCase``). These tests still require using the ``Factories`` trait to boot
-Foundry but will not have doctrine available. Factories created in these tests will not be persisted (calling
-``->withoutPersisting()`` is not necessary). Because the bundle is not available in these tests,
-any bundle configuration you have will not be picked up.
+``Symfony\Bundle\FrameworkBundle\Test\KernelTestCase``). These tests still require enabling Foundry with the PHPUnit extension
+(or using the ``Factories`` trait if you still use PHPUnit 9) to boot Foundry but will not have doctrine available.
+Factories created in these tests will not be persisted (calling ``->withoutPersisting()`` is not necessary). Because
+the bundle is not available in these tests, any bundle configuration you have will not be picked up.
 
 ::
 
@@ -2612,19 +2625,19 @@ Full Default Bundle Configuration
         orm:
             reset:
 
-                # DBAL connections to reset with ResetDatabase trait
+                # DBAL connections to reset with ResetDatabase attribute
                 connections:
 
                     # Default:
                     - default
 
-                # Entity Managers to reset with ResetDatabase trait
+                # Entity Managers to reset with ResetDatabase attribute
                 entity_managers:
 
                     # Default:
                     - default
 
-                # Reset mode to use with ResetDatabase trait
+                # Reset mode to use with ResetDatabase attribute
                 mode:                 schema # One of "schema"; "migrate"
                 migrations:
 
@@ -2634,7 +2647,7 @@ Full Default Bundle Configuration
         mongo:
             reset:
 
-                # Document Managers to reset with ResetDatabase trait
+                # Document Managers to reset with ResetDatabase attribute
                 document_managers:
 
                     # Default:

phpunit-deprecation-baseline.xml

@@ -7,10 +7,16 @@
             <issue><![CDATA[Since symfony/var-exporter 7.3: Generating lazy proxy for class "Zenstruck\Foundry\Tests\Integration\ForceFactoriesTraitUsage\SomeObject" is deprecated; leverage native lazy objects instead.]]></issue>
             <issue><![CDATA[Since symfony/var-exporter 7.3: Using ProxyHelper::generateLazyGhost() is deprecated, use native lazy objects instead.]]></issue>
             <issue><![CDATA[Since symfony/var-exporter 7.3: The "Symfony\Component\VarExporter\LazyGhostTrait" trait is deprecated, use native lazy objects instead.]]></issue>
+            <issue><![CDATA[Since symfony/var-exporter 7.3: The "Symfony\Component\VarExporter\LazyProxyTrait" trait is deprecated, use native lazy objects instead.]]></issue>
+            <issue><![CDATA[Since symfony/var-exporter 7.3: Generating lazy proxy for class "Zenstruck\Foundry\Tests\Fixture\Entity\GlobalEntity" is deprecated; leverage native lazy objects instead.]]></issue>
 
             <issue><![CDATA[Since zenstruck/foundry 2.7: Proxy usage is deprecated in PHP 8.4. Use directly PersistentObjectFactory, Foundry now leverages the native PHP lazy system to auto-refresh objects.]]></issue>
             <issue><![CDATA[Since zenstruck/foundry 2.7: Proxy usage is deprecated in PHP 8.4. You should extend directly PersistentObjectFactory in your factories.
 Foundry now leverages the native PHP lazy system to auto-refresh objects (it can be enabled with "zenstruck_foundry.enable_auto_refresh_with_lazy_objects" configuration).
+See https://github.com/zenstruck/foundry/blob/2.x/UPGRADE-2.7.md to upgrade.]]></issue>
+            <issue><![CDATA[Since zenstruck/foundry 2.7: Function proxy() is deprecated and will be removed in Foundry 3.
+Proxy usage is deprecated in PHP 8.4. You should extend directly PersistentObjectFactory in your factories.
+Foundry now leverages the native PHP lazy system to auto-refresh objects (it can be enabled with "zenstruck_foundry.enable_auto_refresh_with_lazy_objects" configuration).
 See https://github.com/zenstruck/foundry/blob/2.x/UPGRADE-2.7.md to upgrade.]]></issue>
             <issue><![CDATA[Since zenstruck/foundry 2.8: Trait Zenstruck\Foundry\Test\Factories is deprecated and will be removed in Foundry 3.]]></issue>
             <issue><![CDATA[Since zenstruck/foundry 2.8: Not using Foundry's PHPUnit extension is deprecated and will throw an error in Foundry 3.]]></issue>

src/Attribute/ResetDatabase.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <kevinbond@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Foundry\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class ResetDatabase
+{
+}

src/Configuration.php

@@ -19,9 +19,8 @@
 use Zenstruck\Foundry\InMemory\CannotEnableInMemory;
 use Zenstruck\Foundry\InMemory\InMemoryRepositoryRegistry;
 use Zenstruck\Foundry\Persistence\PersistenceManager;
-use Zenstruck\Foundry\PHPUnit\FoundryExtension;
-use Zenstruck\Foundry\Test\Factories;
 use Zenstruck\Foundry\Persistence\Proxy\PersistedObjectsTracker;
+use Zenstruck\Foundry\PHPUnit\FoundryExtension;
 
 /**
  * @author Kevin Bond <kevinbond@gmail.com>

src/PHPUnit/AttributeReader.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <kevinbond@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Foundry\PHPUnit;
+
+/**
+ * @internal
+ * @author Nicolas PHILIPPE <nikophil@gmail.com>
+ */
+final class AttributeReader
+{
+    private function __construct()
+    {
+    }
+
+    /**
+     * @template T of object
+     *
+     * @param class-string<T> $attributeClass
+     *
+     * @return list<\ReflectionAttribute<T>>
+     */
+    public static function collectAttributesFromClassAndParents(string $attributeClass, \ReflectionClass $class): array // @phpstan-ignore missingType.generics
+    {
+        return [
+            ...$class->getAttributes($attributeClass),
+            ...(
+                $class->getParentClass()
+                    ? self::collectAttributesFromClassAndParents($attributeClass, $class->getParentClass())
+                    : []
+            ),
+        ];
+    }
+}

src/PHPUnit/BootFoundryOnPreparationStarted.php

@@ -33,7 +33,6 @@ public function notify(Event\Test\PreparationStarted $event): void
             return;
         }
         /** @var Event\Code\TestMethod $test */
-
         $this->bootFoundry($test->className());
     }
 
@@ -55,11 +54,11 @@ private function bootFoundry(string $className): void
 
         // integration test
         Configuration::boot(static function() use ($className): Configuration {
-            if (!KernelTestCaseHelper::getContainerForTestClass($className)->has('.zenstruck_foundry.configuration')) {
+            if (!KernelTestCaseHelper::getContainer($className)->has('.zenstruck_foundry.configuration')) {
                 throw new \LogicException('ZenstruckFoundryBundle is not enabled. Ensure it is added to your config/bundles.php.');
             }
 
-            return KernelTestCaseHelper::getContainerForTestClass($className)->get('.zenstruck_foundry.configuration'); // @phpstan-ignore return.type
+            return KernelTestCaseHelper::getContainer($className)->get('.zenstruck_foundry.configuration'); // @phpstan-ignore return.type
         });
     }
 }