[11.x] Enhance PHPDoc for Eloquent Relations to support precise subclasses

src/Illuminate/Database/Eloquent/Builder.php

@@ -1537,8 +1537,10 @@ protected function createNestedWhere($whereSlice, $boolean = 'and')
     /**
      * Set the relationships that should be eager loaded.
      *
-     * @param  array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string  $relations
-     * @param  (\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string|null  $callback
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(\Closure(TRelation): mixed)|string>|string  $relations
+     * @param  (\Closure(TRelation): mixed)|string|null  $callback
      * @return $this
      */
     public function with($relations, $callback = null)
@@ -1572,7 +1574,9 @@ public function without($relations)
     /**
      * Set the relationships that should be eager loaded while removing any previously added eager loading specifications.
      *
-     * @param  array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(\Closure(TRelation): mixed)|string>|string  $relations
      * @return $this
      */
     public function withOnly($relations)

src/Illuminate/Database/Eloquent/Collection.php

@@ -84,7 +84,9 @@ public function findOrFail($key)
     /**
      * Load a set of relationships onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @return $this
      */
     public function load($relations)
@@ -105,7 +107,9 @@ public function load($relations)
     /**
      * Load a set of aggregations over relationship's column onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @param  string  $column
      * @param  string|null  $function
      * @return $this
@@ -142,7 +146,9 @@ public function loadAggregate($relations, $column, $function = null)
     /**
      * Load a set of relationship counts onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @return $this
      */
     public function loadCount($relations)
@@ -153,7 +159,9 @@ public function loadCount($relations)
     /**
      * Load a set of relationship's max column values onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @param  string  $column
      * @return $this
      */
@@ -165,7 +173,9 @@ public function loadMax($relations, $column)
     /**
      * Load a set of relationship's min column values onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @param  string  $column
      * @return $this
      */
@@ -177,7 +187,9 @@ public function loadMin($relations, $column)
     /**
      * Load a set of relationship's column summations onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @param  string  $column
      * @return $this
      */
@@ -189,7 +201,9 @@ public function loadSum($relations, $column)
     /**
      * Load a set of relationship's average column values onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @param  string  $column
      * @return $this
      */
@@ -201,7 +215,9 @@ public function loadAvg($relations, $column)
     /**
      * Load a set of related existences onto the collection.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @return $this
      */
     public function loadExists($relations)
@@ -212,7 +228,9 @@ public function loadExists($relations)
     /**
      * Load a set of relationships onto the collection if they are not already eager loaded.
      *
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>|string  $relations
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>|string  $relations
      * @return $this
      */
     public function loadMissing($relations)
@@ -283,8 +301,10 @@ protected function loadMissingRelation(self $models, array $path)
     /**
      * Load a set of relationships onto the mixed relationship collection.
      *
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
      * @param  string  $relation
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>  $relations
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>  $relations
      * @return $this
      */
     public function loadMorph($relation, $relations)
@@ -300,8 +320,10 @@ public function loadMorph($relation, $relations)
     /**
      * Load a set of relationship counts onto the mixed relationship collection.
      *
+     * @template-covariant TRelation of \Illuminate\Database\Eloquent\Relations\Relation
+     *
      * @param  string  $relation
-     * @param  array<array-key, array|(callable(\Illuminate\Database\Eloquent\Relations\Relation<*, *, *>): mixed)|string>  $relations
+     * @param  array<array-key, array|(callable(TRelation): mixed)|string>  $relations
      * @return $this
      */
     public function loadMorphCount($relation, $relations)

types/Database/Eloquent/Builder.php

@@ -6,6 +6,7 @@
 use Illuminate\Database\Eloquent\HasBuilder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 use Illuminate\Database\Query\Builder as QueryBuilder;
 use User;
@@ -25,14 +26,23 @@ function test(
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->whereNot('status', 'active'));
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with('relation'));
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with(['relation' => ['foo' => fn ($q) => $q]]));
-    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with(['relation' => function ($query) {
-        // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with(['relation' => function (HasMany $query): void {
+        assertType('Illuminate\Database\Eloquent\Relations\HasMany', $query);
+    }]));
+    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with(['relation' => function (HasOne $query): void {
+        assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
+    }]));
+    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->with(['relation' => function (MorphTo $query): void {
+        assertType('Illuminate\Database\Eloquent\Relations\MorphTo', $query);
     }]));
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->without('relation'));
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->withOnly(['relation']));
     assertType('Illuminate\Database\Eloquent\Builder<User>', $query->withOnly(['relation' => ['foo' => fn ($q) => $q]]));
-    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->withOnly(['relation' => function ($query) {
-        // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->withOnly(['relation' => function (MorphTo $query) {
+        assertType('Illuminate\Database\Eloquent\Relations\MorphTo', $query);
+    }]));
+    assertType('Illuminate\Database\Eloquent\Builder<User>', $query->withOnly(['relation' => function (HasOne $query): void {
+        assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
     }]));
     assertType('array<int, User>', $query->getModels());
     assertType('array<int, User>', $query->eagerLoadRelations([]));

types/Database/Eloquent/Collection.php

@@ -1,5 +1,10 @@
 <?php
 
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
+use Illuminate\Database\Eloquent\Relations\MorphTo;
+
 use function PHPStan\Testing\assertType;
 
 $collection = User::all();
@@ -11,77 +16,77 @@
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->load('string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->load(['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->load(['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->load(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->load(['string' => function (BelongsTo $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\BelongsTo', $query);
 }]));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate('string', 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate(['string'], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate(['string' => ['foo' => fn ($q) => $q]], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate(['string'], 'string', 'string'));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAggregate(['string' => function (BelongsTo $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\BelongsTo', $query);
 }], 'string', 'string'));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadCount('string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadCount(['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadCount(['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadCount(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadCount(['string' => function (HasOne $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
 }]));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMax('string', 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMax(['string'], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMax(['string' => ['foo' => fn ($q) => $q]], 'string'));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMax(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMax(['string' => function (HasMany $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasMany', $query);
 }], 'string'));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMin('string', 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMin(['string'], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMin(['string' => ['foo' => fn ($q) => $q]], 'string'));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMin(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMin(['string' => function (HasOne $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
 }], 'string'));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadSum('string', 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadSum(['string'], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadSum(['string' => ['foo' => fn ($q) => $q]], 'string'));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadSum(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadSum(['string' => function (HasMany $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasMany', $query);
 }], 'string'));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAvg('string', 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAvg(['string'], 'string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAvg(['string' => ['foo' => fn ($q) => $q]], 'string'));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAvg(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadAvg(['string' => function (BelongsTo $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\BelongsTo', $query);
 }], 'string'));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadExists('string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadExists(['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadExists(['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadExists(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadExists(['string' => function (MorphTo $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\MorphTo', $query);
 }]));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMissing('string'));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMissing(['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMissing(['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMissing(['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMissing(['string' => function (HasOne $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
 }]));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorph('string', ['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorph('string', ['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorph('string', ['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorph('string', ['string' => function (HasMany $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasMany', $query);
 }]));
 
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorphCount('string', ['string']));
 assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorphCount('string', ['string' => ['foo' => fn ($q) => $q]]));
-assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorphCount('string', ['string' => function ($query) {
-    // assertType('Illuminate\Database\Eloquent\Relations\Relation<*,*,*>', $query);
+assertType('Illuminate\Database\Eloquent\Collection<int, User>', $collection->loadMorphCount('string', ['string' => function (HasOne $query) {
+    assertType('Illuminate\Database\Eloquent\Relations\HasOne', $query);
 }]));
 
 assertType('bool', $collection->contains(function ($user) {