Enhancement: Add template annotations

CHANGELOG.md

@@ -26,6 +26,7 @@ For a full diff see [`fa9c564...master`][fa9c564...master].
 * Started throwing an `Exception\EntityDefinitionAlreadyRegistered` exception instead of a generic `Exception` when an entity definition for a class name has already been registered ([#106]), by [@localheinz]
 * Added `$faker` parameter to `Definition\Definition::accept()` and `Definition\Definitions::registerWith()`, providing and requiring to pass in an instance of `Faker\Generator` ([#117]), by [@localheinz]
 * Started throwing an `Exception\ClassNotFound` exception instead of a generic `Exception` when a class was not found ([#125]), by [@localheinz]
+* Added `@template` annotations to assist with static code analysis ([#128]), by [@localheinz]
 
 ### Fixed
 
@@ -72,5 +73,6 @@ For a full diff see [`fa9c564...master`][fa9c564...master].
 [#124]: https://github.com/ergebnis/factory-bot/pull/124
 [#125]: https://github.com/ergebnis/factory-bot/pull/125
 [#126]: https://github.com/ergebnis/factory-bot/pull/126
+[#128]: https://github.com/ergebnis/factory-bot/pull/128
 
 [@localheinz]: https://github.com/localheinz

phpstan-baseline.neon

@@ -95,6 +95,16 @@ parameters:
 			count: 1
 			path: test/Fixture/FixtureFactory/Entity/User.php
 
+		-
+			message: "#^Parameter \\#1 \\$className of method Ergebnis\\\\FactoryBot\\\\FixtureFactory\\:\\:defineEntity\\(\\) expects class\\-string\\<NotAClass\\>, string given\\.$#"
+			count: 1
+			path: test/Unit/FixtureFactoryTest.php
+
+		-
+			message: "#^Call to static method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with 'Ergebnis\\\\\\\\FactoryBot…' and Ergebnis\\\\FactoryBot\\\\Test\\\\Fixture\\\\FixtureFactory\\\\Entity\\\\User will always evaluate to true\\.$#"
+			count: 1
+			path: test/Unit/FixtureFactoryTest.php
+
 		-
 			message: "#^Call to static method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with 'Ergebnis\\\\\\\\FactoryBot…' and Ergebnis\\\\FactoryBot\\\\Test\\\\Fixture\\\\FixtureFactory\\\\Entity\\\\Repository will always evaluate to true\\.$#"
 			count: 2
@@ -105,6 +115,11 @@ parameters:
 			count: 2
 			path: test/Unit/FixtureFactoryTest.php
 
+		-
+			message: "#^Call to static method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with 'Ergebnis\\\\\\\\FactoryBot…' and Ergebnis\\\\FactoryBot\\\\Test\\\\Fixture\\\\FixtureFactory\\\\Entity\\\\Project will always evaluate to true\\.$#"
+			count: 1
+			path: test/Unit/FixtureFactoryTest.php
+
 		-
 			message: "#^Call to static method PHPUnit\\\\Framework\\\\Assert\\:\\:assertInstanceOf\\(\\) with 'Ergebnis\\\\\\\\FactoryBot…' and Ergebnis\\\\FactoryBot\\\\Test\\\\Fixture\\\\FixtureFactory\\\\Entity\\\\Organization will always evaluate to true\\.$#"
 			count: 1

psalm-baseline.xml

@@ -87,6 +87,9 @@
     </MissingClosureParamType>
   </file>
   <file src="test/Unit/FixtureFactoryTest.php">
+    <ArgumentTypeCoercion occurrences="1">
+      <code>$className</code>
+    </ArgumentTypeCoercion>
     <MixedArgument occurrences="2">
       <code>$name</code>
       <code>$fieldValues['name']</code>
@@ -100,5 +103,9 @@
       <code>assertInstanceOf</code>
       <code>assertInstanceOf</code>
     </RedundantCondition>
+    <RedundantConditionGivenDocblockType occurrences="2">
+      <code>assertInstanceOf</code>
+      <code>assertInstanceOf</code>
+    </RedundantConditionGivenDocblockType>
   </file>
 </files>

src/FieldDefinition.php

@@ -67,7 +67,9 @@ public static function sequence($funcOrString, int $firstNum = 1): \Closure
      *
      * The normal semantics of `get()` apply.
      *
-     * @param string $className
+     * @template T
+     *
+     * @param class-string<T> $className
      *
      * @return \Closure
      */
@@ -83,8 +85,10 @@ public static function reference(string $className): \Closure
      *
      * The normal semantics of `get()` apply.
      *
-     * @param string $className
-     * @param int    $count
+     * @template T
+     *
+     * @param class-string<T> $className
+     * @param int             $count
      *
      * @throws Exception\InvalidCount
      *

src/FixtureFactory.php

@@ -45,9 +45,11 @@ public function __construct(ORM\EntityManagerInterface $entityManager)
      *
      * See the readme for a tutorial.
      *
-     * @param string   $className
-     * @param array    $fieldDefinitions
-     * @param \Closure $afterCreate
+     * @template T
+     *
+     * @param class-string<T> $className
+     * @param array           $fieldDefinitions
+     * @param \Closure        $afterCreate
      *
      * @throws Exception\ClassMetadataNotFound
      * @throws Exception\ClassNotFound
@@ -142,13 +144,17 @@ public function defineEntity(string $className, array $fieldDefinitions = [], ?\
      *
      * If you've called `persistOnGet()` then the entity is also persisted.
      *
-     * @param string               $className
+     * @template T
+     *
+     * @param class-string<T>      $className
      * @param array<string, mixed> $fieldOverrides
      *
      * @throws Exception\EntityDefinitionNotRegistered
      * @throws Exception\InvalidFieldNames
+     *
+     * @return T
      */
-    public function get(string $className, array $fieldOverrides = []): object
+    public function get(string $className, array $fieldOverrides = [])
     {
         if (!\array_key_exists($className, $this->entityDefinitions)) {
             throw Exception\EntityDefinitionNotRegistered::for($className);
@@ -172,6 +178,7 @@ public function get(string $className, array $fieldOverrides = []): object
         /** @var ORM\Mapping\ClassMetadata $classMetadata */
         $classMetadata = $entityDefinition->classMetadata();
 
+        /** @var T $entity */
         $entity = $classMetadata->newInstance();
 
         $fieldValues = [];
@@ -205,13 +212,15 @@ public function get(string $className, array $fieldOverrides = []): object
      *
      * If you've called `persistOnGet()` then the entities are also persisted.
      *
-     * @param string $className
-     * @param array  $fieldOverrides
-     * @param int    $count
+     * @template T
+     *
+     * @param class-string<T> $className
+     * @param array           $fieldOverrides
+     * @param int             $count
      *
      * @throws Exception\InvalidCount
      *
-     * @return object[]
+     * @return array<int, T>
      */
     public function getList(string $className, array $fieldOverrides = [], int $count = 1): array
     {