From 2922575c6f08d67cfa02ab4087c56f1c236e8f43 Mon Sep 17 00:00:00 2001
From: Nuno Maduro <enunomaduro@gmail.com>
Date: Mon, 24 Apr 2023 19:49:40 +0100
Subject: [PATCH] [10.x] Uses `@template-covariant` in collections (#46872)

* docs: update collection docs to use template-covariant for the values

This allows developers to use classes with inheritance on collections. See types/Support/Collection.php for an example

* Revert `@template-covariant` on Arrayable

* Apply fixes from StyleCI

---------

Co-authored-by: rvanvelzen <rvanvelzen@swis.nl>
Co-authored-by: StyleCI Bot <bot@styleci.io>
---
 src/Illuminate/Collections/Collection.php     |  3 +-
 src/Illuminate/Collections/Enumerable.php     |  3 +-
 src/Illuminate/Collections/LazyCollection.php |  3 +-
 .../Collections/Traits/EnumeratesValues.php   |  3 +-
 types/Support/Collection.php                  | 42 +++++++++++++++++++
 5 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/src/Illuminate/Collections/Collection.php b/src/Illuminate/Collections/Collection.php
index 10b214128f7f..0fa3ed6b0227 100644
--- a/src/Illuminate/Collections/Collection.php
+++ b/src/Illuminate/Collections/Collection.php
@@ -12,7 +12,8 @@
 
 /**
  * @template TKey of array-key
- * @template TValue
+ *
+ * @template-covariant TValue
  *
  * @implements \ArrayAccess<TKey, TValue>
  * @implements \Illuminate\Support\Enumerable<TKey, TValue>
diff --git a/src/Illuminate/Collections/Enumerable.php b/src/Illuminate/Collections/Enumerable.php
index f1a2f72401c0..a561488e8a59 100644
--- a/src/Illuminate/Collections/Enumerable.php
+++ b/src/Illuminate/Collections/Enumerable.php
@@ -12,7 +12,8 @@
 
 /**
  * @template TKey of array-key
- * @template TValue
+ *
+ * @template-covariant TValue
  *
  * @extends \Illuminate\Contracts\Support\Arrayable<TKey, TValue>
  * @extends \IteratorAggregate<TKey, TValue>
diff --git a/src/Illuminate/Collections/LazyCollection.php b/src/Illuminate/Collections/LazyCollection.php
index 1b7830180df9..39c7ecc4f8a9 100644
--- a/src/Illuminate/Collections/LazyCollection.php
+++ b/src/Illuminate/Collections/LazyCollection.php
@@ -16,7 +16,8 @@
 
 /**
  * @template TKey of array-key
- * @template TValue
+ *
+ * @template-covariant TValue
  *
  * @implements \Illuminate\Support\Enumerable<TKey, TValue>
  */
diff --git a/src/Illuminate/Collections/Traits/EnumeratesValues.php b/src/Illuminate/Collections/Traits/EnumeratesValues.php
index 92d4ec15ebc7..f9614963ae36 100644
--- a/src/Illuminate/Collections/Traits/EnumeratesValues.php
+++ b/src/Illuminate/Collections/Traits/EnumeratesValues.php
@@ -19,7 +19,8 @@
 
 /**
  * @template TKey of array-key
- * @template TValue
+ *
+ * @template-covariant TValue
  *
  * @property-read HigherOrderCollectionProxy $average
  * @property-read HigherOrderCollectionProxy $avg
diff --git a/types/Support/Collection.php b/types/Support/Collection.php
index eefe74fbe8e1..f2f5311c8c85 100644
--- a/types/Support/Collection.php
+++ b/types/Support/Collection.php
@@ -1055,3 +1055,45 @@ class CustomCollection extends Collection
     assertType('int', $int);
     assertType('User', $user);
 }
+
+class Animal
+{
+}
+class Tiger extends Animal
+{
+}
+class Lion extends Animal
+{
+}
+class Zebra extends Animal
+{
+}
+
+class Zoo
+{
+    /**
+     * @var \Illuminate\Support\Collection<int, Animal>
+     */
+    private Collection $animals;
+
+    public function __construct()
+    {
+        $this->animals = collect([
+            new Tiger,
+            new Lion,
+            new Zebra,
+        ]);
+    }
+
+    /**
+     * @return \Illuminate\Support\Collection<int, Animal>
+     */
+    public function getWithoutZebras(): Collection
+    {
+        return $this->animals->filter(fn (Animal $animal) => ! $animal instanceof Zebra);
+    }
+}
+
+$zoo = new Zoo();
+
+assertType('Illuminate\Support\Collection<int, Animal>', $zoo->getWithoutZebras());