[11.x] fix: Model newCollection generics; feat: add HasCollection trait (#52171)

* fix: newCollection generics

* feat: add HasCollection trait

Author: calebdw

src/Illuminate/Database/Eloquent/HasCollection.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Illuminate\Database\Eloquent;
+
+/**
+ * @template TCollection of \Illuminate\Database\Eloquent\Collection
+ */
+trait HasCollection
+{
+    /**
+     * Create a new Eloquent Collection instance.
+     *
+     * @param  array<array-key, \Illuminate\Database\Eloquent\Model>  $models
+     * @return TCollection
+     */
+    public function newCollection(array $models = [])
+    {
+        return new static::$collection($models);
+    }
+}

src/Illuminate/Database/Eloquent/Model.php

@@ -35,6 +35,8 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
         Concerns\HidesAttributes,
         Concerns\GuardsAttributes,
         ForwardsCalls;
+    /** @use HasCollection<\Illuminate\Database\Eloquent\Collection<array-key, static>> */
+    use HasCollection;
 
     /**
      * The connection name for the model.
@@ -218,6 +220,13 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
      */
     protected static string $builder = Builder::class;
 
+    /**
+     * The Eloquent collection class to use for the model.
+     *
+     * @var class-string<\Illuminate\Database\Eloquent\Collection<*, *>>
+     */
+    protected static string $collection = Collection::class;
+
     /**
      * The name of the "created at" column.
      *
@@ -1588,20 +1597,6 @@ protected function newBaseQueryBuilder()
         return $this->getConnection()->query();
     }
 
-    /**
-     * Create a new Eloquent Collection instance.
-     *
-     * @template TKey of array-key
-     * @template TModel of \Illuminate\Database\Eloquent\Model
-     *
-     * @param  array<TKey, TModel>  $models
-     * @return \Illuminate\Database\Eloquent\Collection<TKey, TModel>
-     */
-    public function newCollection(array $models = [])
-    {
-        return new Collection($models);
-    }
-
     /**
      * Create a new pivot model instance.
      *

src/Illuminate/Notifications/DatabaseNotification.php

@@ -3,10 +3,14 @@
 namespace Illuminate\Notifications;
 
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\HasCollection;
 use Illuminate\Database\Eloquent\Model;
 
 class DatabaseNotification extends Model
 {
+    /** @use HasCollection<DatabaseNotificationCollection> */
+    use HasCollection;
+
     /**
      * The "type" of the primary key ID.
      *
@@ -45,6 +49,8 @@ class DatabaseNotification extends Model
         'read_at' => 'datetime',
     ];
 
+    protected static string $collection = DatabaseNotificationCollection::class;
+
     /**
      * Get the notifiable entity that the notification belongs to.
      *
@@ -120,15 +126,4 @@ public function scopeUnread(Builder $query)
     {
         return $query->whereNull('read_at');
     }
-
-    /**
-     * Create a new database notification collection instance.
-     *
-     * @param  array  $models
-     * @return \Illuminate\Notifications\DatabaseNotificationCollection
-     */
-    public function newCollection(array $models = [])
-    {
-        return new DatabaseNotificationCollection($models);
-    }
 }

types/Database/Eloquent/Model.php

@@ -2,12 +2,14 @@
 
 namespace Illuminate\Types\Model;
 
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\HasCollection;
 use Illuminate\Database\Eloquent\Model;
 use User;
 
 use function PHPStan\Testing\assertType;
 
-function test(User $user): void
+function test(User $user, Post $post, Comment $comment): void
 {
     assertType('UserFactory', User::factory(function ($attributes, $model) {
         assertType('array<string, mixed>', $attributes);
@@ -30,14 +32,45 @@ function test(User $user): void
     assertType('Illuminate\Database\Eloquent\Builder<User>', $user->prunable());
     assertType('Illuminate\Database\Eloquent\Relations\MorphMany<Illuminate\Notifications\DatabaseNotification, User>', $user->notifications());
 
-    assertType('Illuminate\Database\Eloquent\Collection<int, User>', $user->newCollection([new User()]));
-    assertType('Illuminate\Database\Eloquent\Collection<string, Illuminate\Types\Model\Post>', $user->newCollection(['foo' => new Post()]));
+    assertType('Illuminate\Database\Eloquent\Collection<(int|string), User>', $user->newCollection([new User()]));
+    assertType('Illuminate\Types\Model\Posts<(int|string), Illuminate\Types\Model\Post>', $post->newCollection(['foo' => new Post()]));
+    assertType('Illuminate\Types\Model\Comments', $comment->newCollection([new Comment()]));
 
     assertType('bool', $user->restore());
     assertType('User', $user->restoreOrCreate());
     assertType('User', $user->createOrRestore());
 }
 
 class Post extends Model
+{
+    /** @use HasCollection<Posts<array-key, static>> */
+    use HasCollection;
+
+    protected static string $collection = Posts::class;
+}
+
+/**
+ * @template TKey of array-key
+ * @template TModel of Post
+ *
+ * @extends Collection<TKey, TModel> */
+class Posts extends Collection
+{
+}
+
+final class Comment extends Model
+{
+    /** @use HasCollection<Comments> */
+    use HasCollection;
+
+    /** @param  array<array-key, Comment>  $models */
+    public function newCollection(array $models = []): Comments
+    {
+        return new Comments($models);
+    }
+}
+
+/** @extends Collection<array-key, Comment> */
+final class Comments extends Collection
 {
 }