chore: update docs + rector set

Author: nikophil

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])
+;
+```

docs/index.rst

@@ -1606,28 +1606,46 @@ 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
 
-        public function test_1(): void
+    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;
+
+        class MyTest extends WebTestCase
         {
-            $post = PostFactory::createOne();
+            use Factories;
 
-            // ...
+            public function test_something(): void
+            {
+                $post = PostFactory::createOne();
+
+                // ...
+            }
         }
-    }
 
 Database Reset
 ~~~~~~~~~~~~~~
@@ -1780,7 +1798,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
         {
@@ -2378,8 +2396,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();

phpunit-deprecation-baseline.xml

@@ -12,8 +12,9 @@
             <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.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>
+
+            <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">

src/Test/Factories.php

@@ -15,7 +15,6 @@
 use PHPUnit\Framework\Attributes\Before;
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 use Zenstruck\Foundry\Configuration;
-
 use Zenstruck\Foundry\PHPUnit\FoundryExtension;
 
 use function Zenstruck\Foundry\Persistence\initialize_proxy_object;
@@ -33,7 +32,7 @@ trait Factories
     public function _beforeHook(): void
     {
         if (FoundryExtension::isEnabled()) {
-            trigger_deprecation('zenstruck/foundry', '2.8', sprintf('Trait %s is deprecated and will be removed in Foundry 3.', Factories::class));
+            trigger_deprecation('zenstruck/foundry', '2.8', \sprintf('Trait %s is deprecated and will be removed in Foundry 3. See https://github.com/zenstruck/foundry/blob/2.x/UPGRADE-2.8.md to upgrade.', Factories::class));
 
             return;
         }

utils/rector/config/foundry-set.php renamed to utils/rector/config/foundry-2.7.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the zenstruck/foundry package.
+ *
+ * (c) Kevin Bond <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Rector\Config\RectorConfig;
+use Rector\Removing\Rector\Class_\RemoveTraitUseRector;
+use Zenstruck\Foundry\Test\Factories;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->ruleWithConfiguration(
+        RemoveTraitUseRector::class,
+        [
+            Factories::class,
+        ]
+    );
+};

utils/rector/config/foundry-2.8.php

@@ -13,6 +13,15 @@
 
 final class FoundrySetList
 {
+    /**
+     * @deprecated use FoundrySetList::FOUNDRY_2_7
+     * @var string
+     */
+    public const REMOVE_PROXIES = self::FOUNDRY_2_7;
+
+    /** @var string */
+    public const FOUNDRY_2_7 = __DIR__.'/../config/foundry-2.7.php';
+
     /** @var string */
-    public const REMOVE_PROXIES = __DIR__.'/../config/foundry-set.php';
+    public const FOUNDRY_2_8 = __DIR__.'/../config/foundry-2.8.php';
 }

utils/rector/src/FoundrySetList.php

@@ -24,6 +24,6 @@ public static function provideData(): \Iterator
 
     public function provideConfigFilePath(): string
     {
-        return __DIR__.'/../../config/foundry-set.php';
+        return __DIR__.'/../../config/foundry-2.7.php';
     }
 }