Makes database factories generic (#39169)

Author: nunomaduro

src/Illuminate/Database/Console/Factories/stubs/factory.stub

@@ -5,6 +5,9 @@ namespace {{ factoryNamespace }};
 use Illuminate\Database\Eloquent\Factories\Factory;
 use {{ namespacedModel }};
 
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\{{ namespacedModel }}>
+ */
 class {{ factory }}Factory extends Factory
 {
     /**

src/Illuminate/Database/Eloquent/Factories/Factory.php

@@ -14,6 +14,9 @@
 use Illuminate\Support\Traits\Macroable;
 use Throwable;
 
+/**
+ * @template TModel of \Illuminate\Database\Eloquent\Model
+ */
 abstract class Factory
 {
     use ForwardsCalls, Macroable {
@@ -23,7 +26,7 @@ abstract class Factory
     /**
      * The name of the factory's corresponding model.
      *
-     * @var string
+     * @var class-string<\Illuminate\Database\Eloquent\Model|TModel>
      */
     protected $model;
 
@@ -137,14 +140,14 @@ public function __construct($count = null,
     /**
      * Define the model's default state.
      *
-     * @return array
+     * @return array<string, mixed>
      */
     abstract public function definition();
 
     /**
      * Get a new factory instance for the given attributes.
      *
-     * @param  callable|array  $attributes
+     * @param  (callable(): array<string, mixed>)|array<string, mixed>  $attributes
      * @return static
      */
     public static function new($attributes = [])
@@ -176,9 +179,9 @@ public function configure()
     /**
      * Get the raw attributes generated by the factory.
      *
-     * @param  array  $attributes
+     * @param  array<string, mixed>  $attributes
      * @param  \Illuminate\Database\Eloquent\Model|null  $parent
-     * @return array
+     * @return array<int|string, mixed>
      */
     public function raw($attributes = [], ?Model $parent = null)
     {
@@ -194,8 +197,8 @@ public function raw($attributes = [], ?Model $parent = null)
     /**
      * Create a single model and persist it to the database.
      *
-     * @param  array  $attributes
-     * @return \Illuminate\Database\Eloquent\Model
+     * @param  array<string, mixed>  $attributes
+     * @return \Illuminate\Database\Eloquent\Model|TModel
      */
     public function createOne($attributes = [])
     {
@@ -205,8 +208,8 @@ public function createOne($attributes = [])
     /**
      * Create a single model and persist it to the database.
      *
-     * @param  array  $attributes
-     * @return \Illuminate\Database\Eloquent\Model
+     * @param  array<string, mixed>  $attributes
+     * @return \Illuminate\Database\Eloquent\Model|TModel
      */
     public function createOneQuietly($attributes = [])
     {
@@ -216,8 +219,8 @@ public function createOneQuietly($attributes = [])
     /**
      * Create a collection of models and persist them to the database.
      *
-     * @param  iterable  $records
-     * @return \Illuminate\Database\Eloquent\Collection
+     * @param  iterable<int, array<string, mixed>>  $records
+     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>
      */
     public function createMany(iterable $records)
     {
@@ -231,8 +234,8 @@ public function createMany(iterable $records)
     /**
      * Create a collection of models and persist them to the database.
      *
-     * @param  iterable  $records
-     * @return \Illuminate\Database\Eloquent\Collection
+     * @param  iterable<int, array<string, mixed>>  $records
+     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>
      */
     public function createManyQuietly(iterable $records)
     {
@@ -244,9 +247,9 @@ public function createManyQuietly(iterable $records)
     /**
      * Create a collection of models and persist them to the database.
      *
-     * @param  array  $attributes
+     * @param  array<string, mixed>  $attributes
      * @param  \Illuminate\Database\Eloquent\Model|null  $parent
-     * @return \Illuminate\Database\Eloquent\Collection|\Illuminate\Database\Eloquent\Model
+     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>|\Illuminate\Database\Eloquent\Model|TModel
      */
     public function create($attributes = [], ?Model $parent = null)
     {
@@ -272,9 +275,9 @@ public function create($attributes = [], ?Model $parent = null)
     /**
      * Create a collection of models and persist them to the database.
      *
-     * @param  array  $attributes
+     * @param  array<string, mixed>  $attributes
      * @param  \Illuminate\Database\Eloquent\Model|null  $parent
-     * @return \Illuminate\Database\Eloquent\Collection|\Illuminate\Database\Eloquent\Model
+     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>|\Illuminate\Database\Eloquent\Model|TModel
      */
     public function createQuietly($attributes = [], ?Model $parent = null)
     {
@@ -286,9 +289,9 @@ public function createQuietly($attributes = [], ?Model $parent = null)
     /**
      * Create a callback that persists a model in the database when invoked.
      *
-     * @param  array  $attributes
+     * @param  array<string, mixed>  $attributes
      * @param  \Illuminate\Database\Eloquent\Model|null  $parent
-     * @return \Closure
+     * @return \Closure(): (\Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>|\Illuminate\Database\Eloquent\Model|TModel)
      */
     public function lazy(array $attributes = [], ?Model $parent = null)
     {
@@ -334,8 +337,8 @@ protected function createChildren(Model $model)
     /**
      * Make a single instance of the model.
      *
-     * @param  callable|array  $attributes
-     * @return \Illuminate\Database\Eloquent\Model
+     * @param  (callable(): array<string, mixed>)|array<string, mixed>  $attributes
+     * @return \Illuminate\Database\Eloquent\Model|TModel
      */
     public function makeOne($attributes = [])
     {
@@ -345,9 +348,9 @@ public function makeOne($attributes = [])
     /**
      * Create a collection of models.
      *
-     * @param  array  $attributes
+     * @param  array<string, mixed>  $attributes
      * @param  \Illuminate\Database\Eloquent\Model|null  $parent
-     * @return \Illuminate\Database\Eloquent\Collection|\Illuminate\Database\Eloquent\Model
+     * @return \Illuminate\Database\Eloquent\Collection<int, \Illuminate\Database\Eloquent\Model|TModel>|\Illuminate\Database\Eloquent\Model|TModel
      */
     public function make($attributes = [], ?Model $parent = null)
     {
@@ -465,7 +468,7 @@ protected function expandAttributes(array $definition)
     /**
      * Add a new state transformation to the model definition.
      *
-     * @param  callable|array  $state
+     * @param  (callable(): array<string, mixed>)|array<string, mixed>  $state
      * @return static
      */
     public function state($state)
@@ -523,7 +526,7 @@ protected function guessRelationship(string $related)
      * Define an attached relationship for the model.
      *
      * @param  \Illuminate\Database\Eloquent\Factories\Factory|\Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model  $factory
-     * @param  callable|array  $pivot
+     * @param  (callable(): array<string, mixed>)|array<string, mixed>  $pivot
      * @param  string|null  $relationship
      * @return static
      */
@@ -562,7 +565,7 @@ public function for($factory, $relationship = null)
     /**
      * Add a new "after making" callback to the model definition.
      *
-     * @param  \Closure  $callback
+     * @param  \Closure(\Illuminate\Database\Eloquent\Model|TModel): mixed  $callback
      * @return static
      */
     public function afterMaking(Closure $callback)
@@ -573,7 +576,7 @@ public function afterMaking(Closure $callback)
     /**
      * Add a new "after creating" callback to the model definition.
      *
-     * @param  \Closure  $callback
+     * @param  \Closure(\Illuminate\Database\Eloquent\Model|TModel): mixed  $callback
      * @return static
      */
     public function afterCreating(Closure $callback)
@@ -656,8 +659,8 @@ protected function newInstance(array $arguments = [])
     /**
      * Get a new model instance.
      *
-     * @param  array  $attributes
-     * @return \Illuminate\Database\Eloquent\Model
+     * @param  array<string, mixed>  $attributes
+     * @return \Illuminate\Database\Eloquent\Model|TModel
      */
     public function newModel(array $attributes = [])
     {
@@ -669,7 +672,7 @@ public function newModel(array $attributes = [])
     /**
      * Get the name of the model that is generated by the factory.
      *
-     * @return string
+     * @return class-string<\Illuminate\Database\Eloquent\Model|TModel>
      */
     public function modelName()
     {
@@ -689,7 +692,7 @@ public function modelName()
     /**
      * Specify the callback that should be invoked to guess model names based on factory names.
      *
-     * @param  callable  $callback
+     * @param  callable(): class-string<\Illuminate\Database\Eloquent\Model|TModel>  $callback
      * @return void
      */
     public static function guessModelNamesUsing(callable $callback)
@@ -711,8 +714,8 @@ public static function useNamespace(string $namespace)
     /**
      * Get a new factory instance for the given model name.
      *
-     * @param  string  $modelName
-     * @return static
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelName
+     * @return \Illuminate\Database\Eloquent\Factories\Factory
      */
     public static function factoryForModel(string $modelName)
     {
@@ -724,7 +727,7 @@ public static function factoryForModel(string $modelName)
     /**
      * Specify the callback that should be invoked to guess factory names based on dynamic relationship names.
      *
-     * @param  callable  $callback
+     * @param  callable(): class-string<\Illuminate\Database\Eloquent\Model|TModel>  $callback
      * @return void
      */
     public static function guessFactoryNamesUsing(callable $callback)
@@ -745,8 +748,8 @@ protected function withFaker()
     /**
      * Get the factory name for the given model name.
      *
-     * @param  string  $modelName
-     * @return string
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelName
+     * @return class-string<\Illuminate\Database\Eloquent\Factories\Factory>
      */
     public static function resolveFactoryName(string $modelName)
     {