[10.x] Uses @template-covariant in collections (laravel#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

@@ -12,7 +12,8 @@
 
 /**
  * @template TKey of array-key
- * @template TValue
+ *
+ * @template-covariant TValue
  *
  * @implements \ArrayAccess<TKey, TValue>
  * @implements \Illuminate\Support\Enumerable<TKey, TValue>

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>

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>
  */

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

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());