[11.x] feat: add generics to Eloquent Builder and Relations (#51851)

* feat: add builder and relation generics

* Update src/Illuminate/Auth/EloquentUserProvider.php

Co-authored-by: Jonas Staudenmeir <[email protected]>

* test: add additional type tests

* feat: create HasBuilder trait

---------

Co-authored-by: Dries Vints <[email protected]>
Co-authored-by: Jonas Staudenmeir <[email protected]>

Author: 3 people

composer.json

@@ -108,7 +108,7 @@
         "nyholm/psr7": "^1.2",
         "orchestra/testbench-core": "^9.1.5",
         "pda/pheanstalk": "^5.0",
-        "phpstan/phpstan": "^1.4.7",
+        "phpstan/phpstan": "^1.11.5",
         "phpunit/phpunit": "^10.5|^11.0",
         "predis/predis": "^2.0.2",
         "resend/resend-php": "^0.10.0",

src/Illuminate/Auth/EloquentUserProvider.php

@@ -27,7 +27,7 @@ class EloquentUserProvider implements UserProvider
     /**
      * The callback that may modify the user retrieval queries.
      *
-     * @var (\Closure(\Illuminate\Database\Eloquent\Builder):mixed)|null
+     * @var (\Closure(\Illuminate\Database\Eloquent\Builder<*>):mixed)|null
      */
     protected $queryCallback;
 
@@ -177,8 +177,10 @@ public function rehashPasswordIfRequired(UserContract $user, #[\SensitiveParamet
     /**
      * Get a new query builder for the model instance.
      *
-     * @param  \Illuminate\Database\Eloquent\Model|null  $model
-     * @return \Illuminate\Database\Eloquent\Builder
+     * @template TModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  TModel|null  $model
+     * @return \Illuminate\Database\Eloquent\Builder<TModel>
      */
     protected function newModelQuery($model = null)
     {
@@ -252,7 +254,7 @@ public function setModel($model)
     /**
      * Get the callback that modifies the query before retrieving users.
      *
-     * @return \Closure|null
+     * @return (\Closure(\Illuminate\Database\Eloquent\Builder<*>):mixed)|null
      */
     public function getQueryCallback()
     {
@@ -262,7 +264,7 @@ public function getQueryCallback()
     /**
      * Sets the callback to modify the query before retrieving users.
      *
-     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder):mixed)|null  $queryCallback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<*>):mixed)|null  $queryCallback
      * @return $this
      */
     public function withQuery($queryCallback = null)

src/Illuminate/Database/Concerns/BuildsQueries.php

@@ -18,6 +18,12 @@
 use InvalidArgumentException;
 use RuntimeException;
 
+/**
+ * @template TValue
+ *
+ * @mixin \Illuminate\Database\Eloquent\Builder
+ * @mixin \Illuminate\Database\Query\Builder
+ */
 trait BuildsQueries
 {
     use Conditionable;
@@ -26,7 +32,7 @@ trait BuildsQueries
      * Chunk the results of the query.
      *
      * @param  int  $count
-     * @param  callable  $callback
+     * @param  callable(\Illuminate\Support\Collection<int, TValue>, int): mixed  $callback
      * @return bool
      */
     public function chunk($count, callable $callback)
@@ -65,9 +71,11 @@ public function chunk($count, callable $callback)
     /**
      * Run a map over each item while chunking.
      *
-     * @param  callable  $callback
+     * @template TReturn
+     *
+     * @param  callable(TValue): TReturn  $callback
      * @param  int  $count
-     * @return \Illuminate\Support\Collection
+     * @return \Illuminate\Support\Collection<int, TReturn>
      */
     public function chunkMap(callable $callback, $count = 1000)
     {
@@ -85,7 +93,7 @@ public function chunkMap(callable $callback, $count = 1000)
     /**
      * Execute a callback over each item while chunking.
      *
-     * @param  callable  $callback
+     * @param  callable(TValue, int): mixed  $callback
      * @param  int  $count
      * @return bool
      *
@@ -106,7 +114,7 @@ public function each(callable $callback, $count = 1000)
      * Chunk the results of a query by comparing IDs.
      *
      * @param  int  $count
-     * @param  callable  $callback
+     * @param  callable(\Illuminate\Support\Collection<int, TValue>, int): mixed  $callback
      * @param  string|null  $column
      * @param  string|null  $alias
      * @return bool
@@ -120,7 +128,7 @@ public function chunkById($count, callable $callback, $column = null, $alias = n
      * Chunk the results of a query by comparing IDs in descending order.
      *
      * @param  int  $count
-     * @param  callable  $callback
+     * @param  callable(\Illuminate\Support\Collection<int, TValue>, int): mixed  $callback
      * @param  string|null  $column
      * @param  string|null  $alias
      * @return bool
@@ -134,7 +142,7 @@ public function chunkByIdDesc($count, callable $callback, $column = null, $alias
      * Chunk the results of a query by comparing IDs in a given order.
      *
      * @param  int  $count
-     * @param  callable  $callback
+     * @param  callable(\Illuminate\Support\Collection<int, TValue>, int): mixed  $callback
      * @param  string|null  $column
      * @param  string|null  $alias
      * @param  bool  $descending
@@ -194,7 +202,7 @@ public function orderedChunkById($count, callable $callback, $column = null, $al
     /**
      * Execute a callback over each item while chunking by ID.
      *
-     * @param  callable  $callback
+     * @param  callable(TValue, int): mixed  $callback
      * @param  int  $count
      * @param  string|null  $column
      * @param  string|null  $alias
@@ -328,7 +336,7 @@ protected function orderedLazyById($chunkSize = 1000, $column = null, $alias = n
      * Execute the query and get the first result.
      *
      * @param  array|string  $columns
-     * @return \Illuminate\Database\Eloquent\Model|object|static|null
+     * @return TValue|null
      */
     public function first($columns = ['*'])
     {
@@ -339,7 +347,7 @@ public function first($columns = ['*'])
      * Execute the query and get the first result if it's the sole matching record.
      *
      * @param  array|string  $columns
-     * @return \Illuminate\Database\Eloquent\Model|object|static|null
+     * @return TValue
      *
      * @throws \Illuminate\Database\RecordsNotFoundException
      * @throws \Illuminate\Database\MultipleRecordsFoundException
@@ -463,7 +471,7 @@ protected function paginateUsingCursor($perPage, $columns = ['*'], $cursorName =
     /**
      * Get the original column name of the given column, without any aliasing.
      *
-     * @param  \Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder  $builder
+     * @param  \Illuminate\Database\Query\Builder|\Illuminate\Database\Eloquent\Builder<*>  $builder
      * @param  string  $parameter
      * @return string
      */