refactor(maker): deprecate --with-phpdocs for PHP >=8.4 (#952)

nikophil · nikophil · commit 3e23fda18a00 · 2025-08-28T18:43:54.000+02:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -209,53 +209,6 @@ This command will generate a ``PostFactory`` class that looks like this:
                 make_factory:
                     add_hints: false
 
-.. note::
-
-    You can add the option ``--with-phpdoc`` in order to add the following ``@method`` docblocks.
-    This would ease autocompletion in your IDE (might be not useful anymore since Foundry v2, at least in PHPStorm):
-
-::
-
-        /**
-         * @method        Post create(array|callable $attributes = [])
-         * @method static Post createOne(array $attributes = [])
-         * @method static Post find(object|array|mixed $criteria)
-         * @method static Post findOrCreate(array $attributes)
-         * @method static Post first(string $sortBy = 'id')
-         * @method static Post last(string $sortBy = 'id')
-         * @method static Post random(array $attributes = [])
-         * @method static Post randomOrCreate(array $attributes = []))
-         * @method static PostRepository|RepositoryProxy repository()
-         * @method static Post[] all()
-         * @method static Post[] createMany(int $number, array|callable $attributes = [])
-         * @method static Post[] createSequence(iterable|callable $sequence)
-         * @method static Post[] findBy(array $attributes)
-         * @method static Post[] randomRange(int $min, int $max, array $attributes = []))
-         * @method static Post[] randomRangeOrCreate(int $min, int $max, array $attributes = [])
-         * @method static Post[] randomSet(int $number, array $attributes = []))
-         *
-         * @phpstan-method Post create(array|callable $attributes = [])
-         * @phpstan-method static Post createOne(array $attributes = [])
-         * @phpstan-method static Post find(object|array|mixed $criteria)
-         * @phpstan-method static Post findOrCreate(array $attributes)
-         * @phpstan-method static Post first(string $sortBy = 'id')
-         * @phpstan-method static Post last(string $sortBy = 'id')
-         * @phpstan-method static Post random(array $attributes = [])
-         * @phpstan-method static Post randomOrCreate(array $attributes = [])
-         * @phpstan-method static list<Post> all()
-         * @phpstan-method static list<Post> createMany(int $number, array|callable $attributes = [])
-         * @phpstan-method static list<Post> createSequence(array|callable $sequence)
-         * @phpstan-method static list<Post> findBy(array $attributes)
-         * @phpstan-method static list<Post> randomRange(int $min, int $max, array $attributes = [])
-         * @phpstan-method static list<Post> randomRangeOrCreate(int $min, int $max, array $attributes = [])
-         * @phpstan-method static list<Post> randomSet(int $number, array $attributes = [])
-         * @phpstan-method static RepositoryDecorator<Post, ObjectRepository<Post>> repository()
-         */
-        final class PostFactory extends PersistentObjectFactory
-        {
-            // ...
-        }
-
 .. _defaults:
 
 In the ``defaults()``, you can return an array of all default values that any new object
diff --git a/src/Maker/Factory/MakeFactoryData.php b/src/Maker/Factory/MakeFactoryData.php
@@ -17,6 +17,7 @@
 use Symfony\Bundle\MakerBundle\Util\ClassNameDetails;
 use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
 use Zenstruck\Foundry\ObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
 use Zenstruck\Foundry\Persistence\Proxy;
 use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;
@@ -85,7 +86,9 @@ public function getObjectShortName(): string
      */
     public function getFactoryClass(): string
     {
-        return $this->isPersisted() ? PersistentProxyObjectFactory::class : ObjectFactory::class;
+        return $this->isPersisted()
+            ? (\PHP_VERSION_ID >= 80400 ? PersistentObjectFactory::class : PersistentProxyObjectFactory::class)
+            : ObjectFactory::class;
     }
 
     public function getFactoryClassShortName(): string
diff --git a/src/Maker/MakeFactory.php b/src/Maker/MakeFactory.php
@@ -77,6 +77,14 @@ public function configureCommand(Command $command, InputConfiguration $inputConf
 
     public function interact(InputInterface $input, ConsoleStyle $io, Command $command): void
     {
+        if ($input->getOption('with-phpdoc') && \PHP_VERSION_ID >= 80400) {
+            trigger_deprecation(
+                'zenstruck/foundry',
+                '2.7',
+                'The --with-phpdoc option is deprecated and will be removed in 3.0.',
+            );
+        }
+
         if (!$this->doctrineEnabled() && !$input->getOption('no-persistence')) {
             $io->text('// Note: Doctrine not enabled: auto-activating <fg=yellow>--no-persistence</> option.');
             $io->newLine();
diff --git a/tests/Fixture/Maker/expected/can_create_factory.php b/tests/Fixture/Maker/expected/can_create_factory.php
@@ -11,13 +11,13 @@
 
 namespace App\Factory;
 
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Category;
 
 /**
- * @extends PersistentProxyObjectFactory<Category>
+ * @extends PersistentObjectFactory<Category>
  */
-final class CategoryFactory extends PersistentProxyObjectFactory
+final class CategoryFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_for_entity_with_repository.php b/tests/Fixture/Maker/expected/can_create_factory_for_entity_with_repository.php
@@ -12,14 +12,14 @@
 namespace App\Factory;
 
 use Doctrine\ORM\EntityRepository;
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Persistence\Proxy;
 use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;
 use Zenstruck\Foundry\Tests\Fixture\Entity\GenericEntity;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Repository\GenericEntityRepository;
 
 /**
- * @extends PersistentProxyObjectFactory<GenericEntity>
+ * @extends PersistentObjectFactory<GenericEntity>
  *
  * @method        GenericEntity|Proxy                              create(array|callable $attributes = [])
  * @method static GenericEntity|Proxy                              createOne(array $attributes = [])
@@ -55,7 +55,7 @@
  * @phpstan-method static list<GenericEntity&Proxy<GenericEntity>> randomRangeOrCreate(int $min, int $max, array $attributes = [])
  * @phpstan-method static list<GenericEntity&Proxy<GenericEntity>> randomSet(int $number, array $attributes = [])
  */
-final class GenericEntityFactory extends PersistentProxyObjectFactory
+final class GenericEntityFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_interactively.php b/tests/Fixture/Maker/expected/can_create_factory_interactively.php
@@ -11,13 +11,13 @@
 
 namespace App\Factory;
 
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Contact;
 
 /**
- * @extends PersistentProxyObjectFactory<Contact>
+ * @extends PersistentObjectFactory<Contact>
  */
-final class ContactFactory extends PersistentProxyObjectFactory
+final class ContactFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_all_fields.php b/tests/Fixture/Maker/expected/can_create_factory_with_all_fields.php
@@ -11,13 +11,13 @@
 
 namespace App\Factory;
 
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Entity\GenericEntity;
 
 /**
- * @extends PersistentProxyObjectFactory<GenericEntity>
+ * @extends PersistentObjectFactory<GenericEntity>
  */
-final class GenericEntityFactory extends PersistentProxyObjectFactory
+final class GenericEntityFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_odm.php b/tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_odm.php
@@ -11,13 +11,13 @@
 
 namespace App\Factory;
 
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Document\WithEmbeddableDocument;
 
 /**
- * @extends PersistentProxyObjectFactory<WithEmbeddableDocument>
+ * @extends PersistentObjectFactory<WithEmbeddableDocument>
  */
-final class WithEmbeddableDocumentFactory extends PersistentProxyObjectFactory
+final class WithEmbeddableDocumentFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_orm.php b/tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_orm.php
@@ -11,13 +11,13 @@
 
 namespace App\Factory;
 
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Entity\WithEmbeddableEntity;
 
 /**
- * @extends PersistentProxyObjectFactory<WithEmbeddableEntity>
+ * @extends PersistentObjectFactory<WithEmbeddableEntity>
  */
-final class WithEmbeddableEntityFactory extends PersistentProxyObjectFactory
+final class WithEmbeddableEntityFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_static_analysis_annotations_with_data_set_phpstan.php b/tests/Fixture/Maker/expected/can_create_factory_with_static_analysis_annotations_with_data_set_phpstan.php
@@ -12,13 +12,13 @@
 namespace App\Tests\Factory;
 
 use Doctrine\ORM\EntityRepository;
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Persistence\Proxy;
 use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Category;
 
 /**
- * @extends PersistentProxyObjectFactory<Category>
+ * @extends PersistentObjectFactory<Category>
  *
  * @method        Category|Proxy                            create(array|callable $attributes = [])
  * @method static Category|Proxy                            createOne(array $attributes = [])
@@ -54,7 +54,7 @@
  * @phpstan-method static list<Category&Proxy<Category>> randomRangeOrCreate(int $min, int $max, array $attributes = [])
  * @phpstan-method static list<Category&Proxy<Category>> randomSet(int $number, array $attributes = [])
  */
-final class CategoryFactory extends PersistentProxyObjectFactory
+final class CategoryFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_static_analysis_annotations_with_data_set_psalm.php b/tests/Fixture/Maker/expected/can_create_factory_with_static_analysis_annotations_with_data_set_psalm.php
@@ -12,13 +12,13 @@
 namespace App\Tests\Factory;
 
 use Doctrine\ORM\EntityRepository;
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Persistence\Proxy;
 use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Category;
 
 /**
- * @extends PersistentProxyObjectFactory<Category>
+ * @extends PersistentObjectFactory<Category>
  *
  * @method        Category|Proxy                            create(array|callable $attributes = [])
  * @method static Category|Proxy                            createOne(array $attributes = [])
@@ -54,7 +54,7 @@
  * @psalm-method static list<Category&Proxy<Category>> randomRangeOrCreate(int $min, int $max, array $attributes = [])
  * @psalm-method static list<Category&Proxy<Category>> randomSet(int $number, array $attributes = [])
  */
-final class CategoryFactory extends PersistentProxyObjectFactory
+final class CategoryFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Fixture/Maker/expected/can_create_factory_with_uid.php b/tests/Fixture/Maker/expected/can_create_factory_with_uid.php
@@ -12,13 +12,13 @@
 namespace App\Factory;
 
 use Symfony\Component\Uid\Uuid;
-use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
+use Zenstruck\Foundry\Persistence\PersistentObjectFactory;
 use Zenstruck\Foundry\Tests\Fixture\Entity\WithUidColumn;
 
 /**
- * @extends PersistentProxyObjectFactory<WithUidColumn>
+ * @extends PersistentObjectFactory<WithUidColumn>
  */
-final class WithUidColumnFactory extends PersistentProxyObjectFactory
+final class WithUidColumnFactory extends PersistentObjectFactory
 {
     /**
      * @see https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html#factories-as-services
diff --git a/tests/Integration/Maker/MakeFactoryTest.php b/tests/Integration/Maker/MakeFactoryTest.php
@@ -13,6 +13,8 @@
 
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\Group;
+use PHPUnit\Framework\Attributes\IgnoreDeprecations;
+use PHPUnit\Framework\Attributes\RequiresPhp;
 use PHPUnit\Framework\Attributes\Test;
 use Symfony\Bundle\FrameworkBundle\Console\Application;
 use Symfony\Bundle\MakerBundle\Exception\RuntimeCommandException;
@@ -32,8 +34,10 @@
 /**
  * @author Kevin Bond <kevinbond@gmail.com>
  * @group maker
+ * @requires PHP >=8.4
  */
 #[Group('maker')]
+#[RequiresPhp('>=8.4')]
 final class MakeFactoryTest extends MakerTestCase
 {
     private const PHPSTAN_PATH = __DIR__.'/../../..'.FactoryGenerator::PHPSTAN_PATH;
@@ -154,6 +158,7 @@ public function can_create_factory_in_test_dir(): void
      */
     #[Test]
     #[DataProvider('scaToolProvider')]
+    #[IgnoreDeprecations]
     public function can_create_factory_with_static_analysis_annotations(string $scaTool): void
     {
         if (!\getenv('DATABASE_URL')) {
@@ -182,6 +187,7 @@ public static function scaToolProvider(): iterable
      * @test
      */
     #[Test]
+    #[IgnoreDeprecations]
     public function can_create_factory_for_entity_with_repository(): void
     {
         if (!\getenv('DATABASE_URL')) {
