feat: force PHPUnit extension usage

Author: nikophil

.github/workflows/phpunit.yml

@@ -213,7 +213,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
@@ -244,7 +244,7 @@ jobs:
 
       - name: Test
         run: |
-          vendor/bin/phpunit tests/Unit --exclude-group legacy-proxy
+          vendor/bin/phpunit tests/Unit
 
   test-with-paratest:
     name: Test with paratest

UPGRADE-2.7.md

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

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

docs/index.rst

@@ -1683,28 +1683,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.9
 
-        public function test_1(): void
+    The ability to globally enable Foundry with PHPUnit extension was introduced in Foundry 2.9 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
 ~~~~~~~~~~~~~~
@@ -1857,7 +1875,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
         {
@@ -2455,8 +2473,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();

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

@@ -17,16 +17,6 @@ check_phpunit_version() {
     fi
 }
 
-can_use_legacy_proxies() {
-    INSTALLED_SYMFONY_VERSION=$(${COMPOSER_BIN} info symfony/var-exporter | grep versions |  cut -c 15-)
-
-    if [[ "${INSTALLED_SYMFONY_VERSION}" == "8"* ]]; then
-      echo 0;
-    else
-      echo 1;
-    fi
-}
-
 ### >> load env vars from .env files if not in CI and not from a composer script
 if [ -z "${CI:-}" ] ; then
   source .env

phpunit-deprecation-baseline.xml

@@ -14,7 +14,9 @@
 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.9: 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.9.md to upgrade.]]></issue>
+            <issue><![CDATA[Since zenstruck/foundry 2.9: 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.9.md to upgrade.]]></issue>
+
             <issue><![CDATA[Since doctrine/mongodb-odm 2.14: Not using native lazy objects is deprecated and will be impossible in Doctrine MongoDB ODM 3.0.]]></issue>
             <issue><![CDATA[Since symfony/framework-bundle 7.3: Not setting the "property_info.with_constructor_extractor" option explicitly is deprecated because its default value will change in version 8.0.]]></issue>
             <issue><![CDATA[Since symfony/console 7.4: The "Symfony\Component\Console\Application::add()" method is deprecated and will be removed in Symfony 8.0, use "Symfony\Component\Console\Application::addCommand()" instead.]]></issue>

src/Configuration.php

@@ -21,6 +21,7 @@
 use Zenstruck\Foundry\InMemory\InMemoryRepositoryRegistry;
 use Zenstruck\Foundry\Persistence\PersistedObjectsTracker;
 use Zenstruck\Foundry\Persistence\PersistenceManager;
+use Zenstruck\Foundry\PHPUnit\FoundryExtension;
 
 /**
  * @author Kevin Bond <[email protected]>
@@ -129,7 +130,9 @@ public static function instance(): self
             throw new FoundryNotBooted();
         }
 
-        FactoriesTraitNotUsed::throwIfComingFromKernelTestCaseWithoutFactoriesTrait();
+        if (!FoundryExtension::isEnabled()) {
+            FactoriesTraitNotUsed::throwIfComingFromKernelTestCaseWithoutFactoriesTrait();
+        }
 
         return \is_callable(self::$instance) ? (self::$instance)() : self::$instance;
     }
@@ -143,6 +146,10 @@ public static function isBooted(): bool
     public static function boot(\Closure|self $configuration): void
     {
         self::$instance = $configuration;
+
+        if (FoundryExtension::shouldBeEnabled()) {
+            trigger_deprecation('zenstruck/foundry', '2.9', '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.9.md to upgrade.');
+        }
     }
 
     /** @param \Closure():self|self $configuration */

src/Exception/FoundryNotBooted.php

@@ -11,13 +11,19 @@
 
 namespace Zenstruck\Foundry\Exception;
 
+use Zenstruck\Foundry\PHPUnit\FoundryExtension;
+
 /**
  * @author Kevin Bond <[email protected]>
  */
 final class FoundryNotBooted extends \LogicException
 {
     public function __construct()
     {
-        parent::__construct('Foundry is not yet booted. Ensure ZenstruckFoundryBundle is enabled. If in a test, ensure your TestCase has the Factories trait.');
+        $message = FoundryExtension::shouldBeEnabled()
+            ? 'Foundry is not yet booted. Ensure ZenstruckFoundryBundle is enabled. If in a test, ensure Foundry\'s PHPUnit extension is enabled.'
+            : 'Foundry is not yet booted. Ensure ZenstruckFoundryBundle is enabled. If in a test, ensure your TestCase has the Factories trait.';
+
+        parent::__construct($message);
     }
 }

src/FactoryCollection.php

@@ -125,6 +125,10 @@ public static function range(Factory $factory, int $min, int $max): self
             throw new \InvalidArgumentException('Min must be less than max.');
         }
 
+        if ($factory instanceof PersistentObjectFactory && $factory->isPersisting() && Configuration::instance()->inADataProvider()) {
+            throw new \InvalidArgumentException('Using randomized "range" factory in data provider is not supported.');
+        }
+
         return new self($factory, static fn() => \array_fill(0, \mt_rand($min, $max), []));
     }