feat(2.x, make:facotry): add phpdoc conditionnally with --with-phpdoc…

… option (zenstruck#611)

phpstan.neon

@@ -13,6 +13,7 @@ parameters:
         - message: '#Attribute class PHPUnit\\Framework\\Attributes\\(.*) does not exist.#'
 
     excludePaths:
+        - tests/Fixture/Maker/expected/can_create_factory_with_auto_activated_not_persisted_option.php
         - tests/Fixture/Maker/expected/can_create_factory_interactively.php
         - tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_odm.php
         - tests/Fixture/Maker/expected/can_create_factory_with_embeddable_with_data_set_orm.php

skeleton/Factory.tpl.php

@@ -1,4 +1,4 @@
-<?php /** @var Zenstruck\Foundry\Bundle\Maker\Factory\MakeFactoryData $makeFactoryData */ ?><?php echo "<?php\n"; ?>
+<?php /** @var \Zenstruck\Foundry\Maker\Factory\MakeFactoryData $makeFactoryData */ ?><?php echo "<?php\n"; ?>
 
 namespace <?php echo $namespace; ?>;
 
@@ -11,18 +11,16 @@
 /**
  * @extends <?php echo $makeFactoryData->getFactoryClassShortName(); ?><<?php echo $makeFactoryData->getObjectShortName(); ?>>
 <?php
-if ($makeFactoryData->isPersisted()) {
+if (count($makeFactoryData->getMethodsPHPDoc())) {
     echo " *\n";
     foreach ($makeFactoryData->getMethodsPHPDoc() as $methodPHPDoc) {
         echo "{$methodPHPDoc->toString()}\n";
     }
 
-    if ($makeFactoryData->hasStaticAnalysisTool()) {
-        echo " *\n";
+    echo " *\n";
 
-        foreach ($makeFactoryData->getMethodsPHPDoc() as $methodPHPDoc) {
-            echo "{$methodPHPDoc->toString($makeFactoryData->staticAnalysisTool())}\n";
-        }
+    foreach ($makeFactoryData->getMethodsPHPDoc() as $methodPHPDoc) {
+        echo "{$methodPHPDoc->toString($makeFactoryData->staticAnalysisTool())}\n";
     }
 }
 ?>

src/Factory.php

@@ -172,6 +172,8 @@ final protected function normalizeAttributes(array|callable $attributes = []): a
 
     /**
      * Override to adjust default attributes & config.
+     *
+     * @return static
      */
     protected function initialize(): static
     {

src/Maker/Factory/FactoryGenerator.php

@@ -146,6 +146,7 @@ private function createMakeFactoryData(Generator $generator, string $class, Make
             $repository ?? null,
             $this->staticAnalysisTool(),
             $persisted ?? false,
+            $makeFactoryQuery->addPhpDoc(),
         );
     }
 

src/Maker/Factory/MakeFactoryData.php

@@ -33,12 +33,18 @@ final class MakeFactoryData
     private array $uses;
     /** @var array<string, string> */
     private array $defaultProperties = [];
-    /** @var non-empty-list<MakeFactoryPHPDocMethod> */
+    /** @var list<MakeFactoryPHPDocMethod> */
     private array $methodsInPHPDoc;
 
     // @phpstan-ignore-next-line
-    public function __construct(private \ReflectionClass $object, private ClassNameDetails $factoryClassNameDetails, private ?\ReflectionClass $repository, private string $staticAnalysisTool, private bool $persisted)
-    {
+    public function __construct(
+        private \ReflectionClass $object,
+        private ClassNameDetails $factoryClassNameDetails,
+        private ?\ReflectionClass $repository,
+        private string $staticAnalysisTool,
+        private bool $persisted,
+        bool $withPhpDoc
+    ) {
         $this->uses = [
             $this->getFactoryClass(),
             $object->getName(),
@@ -56,7 +62,7 @@ public function __construct(private \ReflectionClass $object, private ClassNameD
             }
         }
 
-        $this->methodsInPHPDoc = MakeFactoryPHPDocMethod::createAll($this);
+        $this->methodsInPHPDoc = $withPhpDoc ? MakeFactoryPHPDocMethod::createAll($this) : [];
     }
 
     // @phpstan-ignore-next-line
@@ -104,13 +110,13 @@ public function isPersisted(): bool
         return $this->persisted;
     }
 
-    public function hasStaticAnalysisTool(): bool
-    {
-        return self::STATIC_ANALYSIS_TOOL_NONE !== $this->staticAnalysisTool;
-    }
-
     public function staticAnalysisTool(): string
     {
+        // if none was detected, let's fallback on phpstan: both psalm and phpstan can read `@phpstan` annotations
+        if (self::STATIC_ANALYSIS_TOOL_NONE === $this->staticAnalysisTool) {
+            return self::STATIC_ANALYSIS_TOOL_PHPSTAN;
+        }
+
         return $this->staticAnalysisTool;
     }
 

src/Maker/Factory/MakeFactoryPHPDocMethod.php

@@ -24,7 +24,7 @@ public function __construct(private string $objectName, private string $prototyp
     }
 
     /** @return non-empty-list<self> */
-    public static function createAll(MakeFactoryData $makeFactoryData): array
+    public static function  createAll(MakeFactoryData $makeFactoryData): array
     {
         $methods = [];
 

src/Maker/Factory/MakeFactoryQuery.php

@@ -19,8 +19,16 @@
  */
 final class MakeFactoryQuery
 {
-    private function __construct(private string $namespace, private bool $test, private bool $persisted, private bool $allFields, private string $class, private bool $generateAllFactories, private Generator $generator)
-    {
+    private function __construct(
+        private string $namespace,
+        private bool $test,
+        private bool $persisted,
+        private bool $allFields,
+        private bool $withPhpDoc,
+        private string $class,
+        private bool $generateAllFactories,
+        private Generator $generator
+    ) {
     }
 
     public static function fromInput(InputInterface $input, string $class, bool $generateAllFactories, Generator $generator, string $defaultNamespace): self
@@ -30,6 +38,7 @@ public static function fromInput(InputInterface $input, string $class, bool $gen
             test: (bool) $input->getOption('test'),
             persisted: !$input->getOption('no-persistence'),
             allFields: (bool) $input->getOption('all-fields'),
+            withPhpDoc: (bool) $input->getOption('with-phpdoc'),
             class: $class,
             generateAllFactories: $generateAllFactories,
             generator: $generator,
@@ -56,6 +65,11 @@ public function isAllFields(): bool
         return $this->allFields;
     }
 
+    public function addPhpDoc(): bool
+    {
+        return $this->withPhpDoc;
+    }
+
     public function getClass(): string
     {
         return $this->class;

src/Maker/MakeFactory.php

@@ -68,6 +68,7 @@ public function configureCommand(Command $command, InputConfiguration $inputConf
             ->addOption('test', null, InputOption::VALUE_NONE, 'Create in <fg=yellow>tests/</> instead of <fg=yellow>src/</>')
             ->addOption('all-fields', null, InputOption::VALUE_NONE, 'Create defaults for all entity fields, not only required fields')
             ->addOption('no-persistence', null, InputOption::VALUE_NONE, 'Create a factory for an object not managed by Doctrine')
+            ->addOption('with-phpdoc', null, InputOption::VALUE_NONE, 'Adds @method and @phpstan-method to the Factory (can help with autocompletion in some cases)')
         ;
 
         $inputConfig->setArgumentAsNonInteractive('class');

tests/Fixture/Maker/expected/can_create_factory.php

@@ -11,30 +11,11 @@
 
 namespace App\Factory\Category;
 
-use Doctrine\ORM\EntityRepository;
 use Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory;
-use Zenstruck\Foundry\Persistence\Proxy;
-use Zenstruck\Foundry\Persistence\ProxyRepositoryDecorator;
 use Zenstruck\Foundry\Tests\Fixture\Entity\Category\StandardCategory;
 
 /**
  * @extends PersistentProxyObjectFactory<StandardCategory>
- *
- * @method        StandardCategory|Proxy                    create(array|callable $attributes = [])
- * @method static StandardCategory|Proxy                    createOne(array $attributes = [])
- * @method static StandardCategory|Proxy                    find(object|array|mixed $criteria)
- * @method static StandardCategory|Proxy                    findOrCreate(array $attributes)
- * @method static StandardCategory|Proxy                    first(string $sortedField = 'id')
- * @method static StandardCategory|Proxy                    last(string $sortedField = 'id')
- * @method static StandardCategory|Proxy                    random(array $attributes = [])
- * @method static StandardCategory|Proxy                    randomOrCreate(array $attributes = [])
- * @method static EntityRepository|ProxyRepositoryDecorator repository()
- * @method static StandardCategory[]|Proxy[]                all()
- * @method static StandardCategory[]|Proxy[]                createMany(int $number, array|callable $attributes = [])
- * @method static StandardCategory[]|Proxy[]                createSequence(iterable|callable $sequence)
- * @method static StandardCategory[]|Proxy[]                findBy(array $attributes)
- * @method static StandardCategory[]|Proxy[]                randomRange(int $min, int $max, array $attributes = [])
- * @method static StandardCategory[]|Proxy[]                randomSet(int $number, array $attributes = [])
  */
 final class StandardCategoryFactory extends PersistentProxyObjectFactory
 {