feat: add better closure typing in QueriesRelationships (#54452)

laravel · Feb 5, 2025 · 0c53b3c · 0c53b3c
1 parent baba544
commit 0c53b3c
Show file tree

Hide file tree

Showing 2 changed files with 241 additions and 135 deletions.
diff --git a/src/Illuminate/Database/Eloquent/Concerns/QueriesRelationships.php b/src/Illuminate/Database/Eloquent/Concerns/QueriesRelationships.php
@@ -24,11 +24,13 @@ trait QueriesRelationships
     /**
      * Add a relationship count / exists condition to the query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
      * @param  string  $operator
      * @param  int  $count
      * @param  string  $boolean
-     * @param  \Closure|null  $callback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @return $this
      *
      * @throws \RuntimeException
@@ -79,7 +81,7 @@ public function has($relation, $operator = '>=', $count = 1, $boolean = 'and', ?
      * @param  string  $operator
      * @param  int  $count
      * @param  string  $boolean
-     * @param  \Closure|null  $callback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<*>): mixed)|null  $callback
      * @return $this
      */
     protected function hasNested($relations, $operator = '>=', $count = 1, $boolean = 'and', $callback = null)
@@ -121,9 +123,11 @@ public function orHas($relation, $operator = '>=', $count = 1)
     /**
      * Add a relationship count / exists condition to the query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
      * @param  string  $boolean
-     * @param  \Closure|null  $callback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @return $this
      */
     public function doesntHave($relation, $boolean = 'and', ?Closure $callback = null)
@@ -145,8 +149,10 @@ public function orDoesntHave($relation)
     /**
      * Add a relationship count / exists condition to the query with where clauses.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -161,8 +167,8 @@ public function whereHas($relation, ?Closure $callback = null, $operator = '>=',
      *
      * Also load the relationship with same condition.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|null  $callback
+     * @param  string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<*>|\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|null  $callback
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -176,8 +182,10 @@ public function withWhereHas($relation, ?Closure $callback = null, $operator = '
     /**
      * Add a relationship count / exists condition to the query with where clauses and an "or".
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -190,8 +198,10 @@ public function orWhereHas($relation, ?Closure $callback = null, $operator = '>=
     /**
      * Add a relationship count / exists condition to the query with where clauses.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @return $this
      */
     public function whereDoesntHave($relation, ?Closure $callback = null)
@@ -202,8 +212,10 @@ public function whereDoesntHave($relation, ?Closure $callback = null)
     /**
      * Add a relationship count / exists condition to the query with where clauses and an "or".
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|null  $callback
      * @return $this
      */
     public function orWhereDoesntHave($relation, ?Closure $callback = null)
@@ -214,12 +226,14 @@ public function orWhereDoesntHave($relation, ?Closure $callback = null)
     /**
      * Add a polymorphic relationship count / exists condition to the query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
      * @param  string  $operator
      * @param  int  $count
      * @param  string  $boolean
-     * @param  \Closure|null  $callback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @return $this
      */
     public function hasMorph($relation, $types, $operator = '>=', $count = 1, $boolean = 'and', ?Closure $callback = null)
@@ -292,7 +306,7 @@ protected function getBelongsToRelation(MorphTo $relation, $type)
      * Add a polymorphic relationship count / exists condition to the query with an "or".
      *
      * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
+     * @param  string|array<int, string>  $types
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -305,10 +319,12 @@ public function orHasMorph($relation, $types, $operator = '>=', $count = 1)
     /**
      * Add a polymorphic relationship count / exists condition to the query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
      * @param  string  $boolean
-     * @param  \Closure|null  $callback
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @return $this
      */
     public function doesntHaveMorph($relation, $types, $boolean = 'and', ?Closure $callback = null)
@@ -320,7 +336,7 @@ public function doesntHaveMorph($relation, $types, $boolean = 'and', ?Closure $c
      * Add a polymorphic relationship count / exists condition to the query with an "or".
      *
      * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
+     * @param  string|array<int, string>  $types
      * @return $this
      */
     public function orDoesntHaveMorph($relation, $types)
@@ -331,9 +347,11 @@ public function orDoesntHaveMorph($relation, $types)
     /**
      * Add a polymorphic relationship count / exists condition to the query with where clauses.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -346,9 +364,11 @@ public function whereHasMorph($relation, $types, ?Closure $callback = null, $ope
     /**
      * Add a polymorphic relationship count / exists condition to the query with where clauses and an "or".
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, array>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @param  string  $operator
      * @param  int  $count
      * @return $this
@@ -361,9 +381,11 @@ public function orWhereHasMorph($relation, $types, ?Closure $callback = null, $o
     /**
      * Add a polymorphic relationship count / exists condition to the query with where clauses.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @return $this
      */
     public function whereDoesntHaveMorph($relation, $types, ?Closure $callback = null)
@@ -374,9 +396,11 @@ public function whereDoesntHaveMorph($relation, $types, ?Closure $callback = nul
     /**
      * Add a polymorphic relationship count / exists condition to the query with where clauses and an "or".
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|null  $callback
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>, string): mixed)|null  $callback
      * @return $this
      */
     public function orWhereDoesntHaveMorph($relation, $types, ?Closure $callback = null)
@@ -387,8 +411,10 @@ public function orWhereDoesntHaveMorph($relation, $types, ?Closure $callback = n
     /**
      * Add a basic where clause to a relationship query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -407,8 +433,10 @@ public function whereRelation($relation, $column, $operator = null, $value = nul
     /**
      * Add an "or where" clause to a relationship query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -427,8 +455,10 @@ public function orWhereRelation($relation, $column, $operator = null, $value = n
     /**
      * Add a basic count / exists condition to a relationship query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -447,8 +477,10 @@ public function whereDoesntHaveRelation($relation, $column, $operator = null, $v
     /**
      * Add an "or where" clause to a relationship query.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\Relation<*, *, *>|string  $relation
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\Relation<TRelatedModel, *, *>|string  $relation
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -467,9 +499,11 @@ public function orWhereDoesntHaveRelation($relation, $column, $operator = null,
     /**
      * Add a polymorphic relationship condition to the query with a where clause.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -484,9 +518,11 @@ public function whereMorphRelation($relation, $types, $column, $operator = null,
     /**
      * Add a polymorphic relationship condition to the query with an "or where" clause.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -501,9 +537,11 @@ public function orWhereMorphRelation($relation, $types, $column, $operator = nul
     /**
      * Add a polymorphic relationship condition to the query with a doesn't have clause.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this
@@ -518,9 +556,11 @@ public function whereMorphDoesntHaveRelation($relation, $types, $column, $operat
     /**
      * Add a polymorphic relationship condition to the query with an "or doesn't have" clause.
      *
-     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<*, *>|string  $relation
-     * @param  string|array  $types
-     * @param  \Closure|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
+     * @template TRelatedModel of \Illuminate\Database\Eloquent\Model
+     *
+     * @param  \Illuminate\Database\Eloquent\Relations\MorphTo<TRelatedModel, *>|string  $relation
+     * @param  string|array<int, string>  $types
+     * @param  (\Closure(\Illuminate\Database\Eloquent\Builder<TRelatedModel>): mixed)|string|array|\Illuminate\Contracts\Database\Query\Expression  $column
      * @param  mixed  $operator
      * @param  mixed  $value
      * @return $this