feat(2.9): deprecate ResetDatabase trait

.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' || '' }}
@@ -189,7 +190,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [ 8.1, 8.2, 8.3, 8.4 ]
+        php: [ 8.2, 8.3, 8.4 ]
     steps:
       - name: Checkout code
         uses: actions/checkout@v3

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

@@ -52,7 +52,7 @@ return RectorConfig::configure()
         'src',
         'tests'
     ])
-    ->withSets([FoundrySetList::REMOVE_PROXIES])
+    ->withSets([FoundrySetList::FOUNDRY_2_7])
 ;
 ```
 

UPGRADE-2.8.md

@@ -0,0 +1,53 @@
+# Migration guide from Foundry 2.7 to 2.8
+
+The main feature of Foundry 2.8 is the deprecation of the `Factories` trait, in favor of the [PHPUnit extension](https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#phpunit-extension)
+shipped by Foundry. It was necessary to remember to add the trait in every test class. And in some cases, Foundry could
+still work even if the trait wasn’t added to the test, which could lead to subtle bugs. Now, Foundry is globally enabled
+once for all.
+
+The trait will be removed in Foundry 3.0, and the extension will be mandatory.
+
+> [!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, remove all the `use Factories;` statements from your factories.
+
+## Rector rules
+
+A Rector set is available to automatically remove the usage of the trait 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_8])
+;
+```

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

@@ -1606,59 +1606,90 @@ Let's look at an example:
 
 .. _enable-foundry-in-your-testcase:
 
-Enable Foundry in your TestCase
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Globally Enable Foundry In PHPUnit
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Add the ``Factories`` trait for tests using factories:
+Add Foundry's `PHPUnit Extension`_ in your `phpunit.xml` file:
 
-::
+.. configuration-block::
 
-    use App\Factory\PostFactory;
-    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
-    use Zenstruck\Foundry\Test\Factories;
+    .. code-block:: xml
 
-    class MyTest extends WebTestCase
-    {
-        use Factories;
+        <phpunit>
+            <extensions>
+                <bootstrap class="Zenstruck\Foundry\PHPUnit\FoundryExtension"/>
+            </extensions>
+        </phpunit>
+
+.. versionadded::  2.8
+
+    The ability to globally enable Foundry with PHPUnit extension was introduced in Foundry 2.8 and requires at least
+    PHPUnit 10.
+
+.. note::
+
+    If you're still using PHPUnit 9, Foundry can be enabled by adding the trait ``Zenstruck\Foundry\Test\Factories``
+    in each test::
+
+        use App\Factory\PostFactory;
+        use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
+        use Zenstruck\Foundry\Test\Factories;
 
-        public function test_1(): void
+        class MyTest extends WebTestCase
         {
-            $post = PostFactory::createOne();
+            use Factories;
 
-            // ...
+            public function test_something(): void
+            {
+                $post = PostFactory::createOne();
+
+                // ...
+            }
         }
-    }
 
 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
@@ -1780,7 +1811,7 @@ Foundry provides a mechanism to automatically refresh inside a functional test t
 
     class MyTest extends WebTestCase
     {
-        use Factories, ResetDatabase;
+        use ResetDatabase;
 
         public function test_with_autorefresh(): void
         {
@@ -2030,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::
@@ -2053,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::
 
@@ -2249,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).
 
@@ -2365,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.
 
 ::
 
@@ -2378,8 +2409,6 @@ any bundle configuration you have will not be picked up.
 
     class MyUnitTest extends TestCase
     {
-        use Factories;
-
         public function some_test(): void
         {
             $post = PostFactory::createOne();
@@ -2596,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:
 
@@ -2618,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:

phpstan.neon

@@ -30,10 +30,6 @@ parameters:
         - identifier: missingType.iterableValue
           path: tests/
 
-        # We support both PHPUnit versions (this method changed in PHPUnit 10)
-        - identifier: function.impossibleType
-          path: src/Test/Factories.php
-
         # PHPStan does not understand PHP version checks
         - message: '#Comparison operation "(<|>|<=|>=)" between int<80\d+, 80\d+> and 80\d+ is always (false|true).#'
 

phpunit-deprecation-baseline.xml

@@ -7,13 +7,20 @@
             <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[Support for MySQL < 8 is deprecated and will be removed in DBAL 5 (AbstractMySQLDriver.php:75 called by AbstractDriverMiddleware.php:32, https://github.com/doctrine/dbal/pull/6343, package doctrine/dbal)]]></issue>
+            <issue><![CDATA[Since zenstruck/foundry 2.8: Trait Zenstruck\Foundry\Test\Factories is deprecated and will be removed in Foundry 3. See https://github.com/zenstruck/foundry/blob/2.x/UPGRADE-2.8.md to upgrade.]]></issue>
+            <issue><![CDATA[Since zenstruck/foundry 2.8: Not using Foundry's PHPUnit extension is deprecated and will throw an error in Foundry 3. See https://github.com/zenstruck/foundry/blob/2.x/UPGRADE-2.8.md to upgrade.]]></issue>
         </line>
     </file>
     <file path="vendor/doctrine/deprecations/src/Deprecation.php">