[11.x] Added generics to paginators (#53512)

* Added generics to paginators

* Added types tests

* Added missing extends in doc and added cursor paginator types

* Formatting

* Formatting

* Formatting

* Moved back to covariant templates

* Formatting

* formatting

---------

Co-authored-by: Taylor Otwell <[email protected]>

Author: EranNL

src/Illuminate/Contracts/Pagination/CursorPaginator.php

@@ -2,6 +2,11 @@
 
 namespace Illuminate\Contracts\Pagination;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ */
 interface CursorPaginator
 {
     /**
@@ -53,7 +58,7 @@ public function nextPageUrl();
     /**
      * Get all of the items being paginated.
      *
-     * @return array
+     * @return array<TKey, TValue>
      */
     public function items();
 

src/Illuminate/Contracts/Pagination/LengthAwarePaginator.php

@@ -2,6 +2,13 @@
 
 namespace Illuminate\Contracts\Pagination;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @extends Paginator<TKey, TValue>
+ */
 interface LengthAwarePaginator extends Paginator
 {
     /**

src/Illuminate/Contracts/Pagination/Paginator.php

@@ -2,6 +2,11 @@
 
 namespace Illuminate\Contracts\Pagination;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ */
 interface Paginator
 {
     /**
@@ -46,7 +51,7 @@ public function previousPageUrl();
     /**
      * Get all of the items being paginated.
      *
-     * @return array
+     * @return array<TKey, TValue>
      */
     public function items();
 

src/Illuminate/Pagination/AbstractCursorPaginator.php

@@ -18,7 +18,11 @@
 use Traversable;
 
 /**
- * @mixin \Illuminate\Support\Collection
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @mixin \Illuminate\Support\Collection<TKey, TValue>
  */
 abstract class AbstractCursorPaginator implements Htmlable, Stringable
 {
@@ -27,7 +31,7 @@ abstract class AbstractCursorPaginator implements Htmlable, Stringable
     /**
      * All of the items being paginated.
      *
-     * @var \Illuminate\Support\Collection
+     * @var \Illuminate\Support\Collection<TKey, TValue>
      */
     protected $items;
 
@@ -388,7 +392,7 @@ public function loadMorphCount($relation, $relations)
     /**
      * Get the slice of items being paginated.
      *
-     * @return array
+     * @return array<TKey, TValue>
      */
     public function items()
     {
@@ -524,7 +528,7 @@ public static function viewFactory()
     /**
      * Get an iterator for the items.
      *
-     * @return \ArrayIterator
+     * @return \ArrayIterator<TKey, TValue>
      */
     public function getIterator(): Traversable
     {

src/Illuminate/Pagination/AbstractPaginator.php

@@ -12,7 +12,11 @@
 use Traversable;
 
 /**
- * @mixin \Illuminate\Support\Collection
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @mixin \Illuminate\Support\Collection<TKey, TValue>
  */
 abstract class AbstractPaginator implements Htmlable, Stringable
 {
@@ -21,7 +25,7 @@ abstract class AbstractPaginator implements Htmlable, Stringable
     /**
      * All of the items being paginated.
      *
-     * @var \Illuminate\Support\Collection
+     * @var \Illuminate\Support\Collection<TKey, TValue>
      */
     protected $items;
 
@@ -310,7 +314,7 @@ public function loadMorphCount($relation, $relations)
     /**
      * Get the slice of items being paginated.
      *
-     * @return array
+     * @return array<TKey, TValue>
      */
     public function items()
     {
@@ -649,7 +653,7 @@ public static function useBootstrapFive()
     /**
      * Get an iterator for the items.
      *
-     * @return \ArrayIterator
+     * @return \ArrayIterator<TKey, TValue>
      */
     public function getIterator(): Traversable
     {
@@ -689,7 +693,7 @@ public function count(): int
     /**
      * Get the paginator's underlying collection.
      *
-     * @return \Illuminate\Support\Collection
+     * @return \Illuminate\Support\Collection<TKey, TValue>
      */
     public function getCollection()
     {
@@ -699,7 +703,7 @@ public function getCollection()
     /**
      * Set the paginator's underlying collection.
      *
-     * @param  \Illuminate\Support\Collection  $collection
+     * @param  \Illuminate\Support\Collection<TKey, TValue>  $collection
      * @return $this
      */
     public function setCollection(Collection $collection)

src/Illuminate/Pagination/CursorPaginator.php

@@ -11,6 +11,18 @@
 use IteratorAggregate;
 use JsonSerializable;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @extends AbstractCursorPaginator<TKey, TValue>
+ *
+ * @implements Arrayable<TKey, TValue>
+ * @implements ArrayAccess<TKey, TValue>
+ * @implements IteratorAggregate<TKey, TValue>
+ * @implements PaginatorContract<TKey, TValue>
+ */
 class CursorPaginator extends AbstractCursorPaginator implements Arrayable, ArrayAccess, Countable, IteratorAggregate, Jsonable, JsonSerializable, PaginatorContract
 {
     /**
@@ -23,7 +35,7 @@ class CursorPaginator extends AbstractCursorPaginator implements Arrayable, Arra
     /**
      * Create a new paginator instance.
      *
-     * @param  mixed  $items
+     * @param  Collection<TKey, TValue>|Arrayable<TKey, TValue>|iterable<TKey, TValue>|null  $items
      * @param  int  $perPage
      * @param  \Illuminate\Pagination\Cursor|null  $cursor
      * @param  array  $options  (path, query, fragment, pageName)
@@ -47,7 +59,7 @@ public function __construct($items, $perPage, $cursor = null, array $options = [
     /**
      * Set the items for the paginator.
      *
-     * @param  mixed  $items
+     * @param  Collection<TKey, TValue>|Arrayable<TKey, TValue>|iterable<TKey, TValue>|null  $items
      * @return void
      */
     protected function setItems($items)

src/Illuminate/Pagination/LengthAwarePaginator.php

@@ -11,6 +11,18 @@
 use IteratorAggregate;
 use JsonSerializable;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @extends AbstractPaginator<TKey, TValue>
+ *
+ * @implements Arrayable<TKey, TValue>
+ * @implements ArrayAccess<TKey, TValue>
+ * @implements IteratorAggregate<TKey, TValue>
+ * @implements LengthAwarePaginatorContract<TKey, TValue>
+ */
 class LengthAwarePaginator extends AbstractPaginator implements Arrayable, ArrayAccess, Countable, IteratorAggregate, Jsonable, JsonSerializable, LengthAwarePaginatorContract
 {
     /**
@@ -30,7 +42,7 @@ class LengthAwarePaginator extends AbstractPaginator implements Arrayable, Array
     /**
      * Create a new paginator instance.
      *
-     * @param  mixed  $items
+     * @param  Collection<TKey, TValue>|Arrayable<TKey, TValue>|iterable<TKey, TValue>|null  $items
      * @param  int  $total
      * @param  int  $perPage
      * @param  int|null  $currentPage

src/Illuminate/Pagination/Paginator.php

@@ -11,6 +11,18 @@
 use IteratorAggregate;
 use JsonSerializable;
 
+/**
+ * @template TKey of array-key
+ *
+ * @template-covariant TValue
+ *
+ * @extends AbstractPaginator<TKey, TValue>
+ *
+ * @implements Arrayable<TKey, TValue>
+ * @implements ArrayAccess<TKey, TValue>
+ * @implements IteratorAggregate<TKey, TValue>
+ * @implements PaginatorContract<TKey, TValue>
+ */
 class Paginator extends AbstractPaginator implements Arrayable, ArrayAccess, Countable, IteratorAggregate, Jsonable, JsonSerializable, PaginatorContract
 {
     /**
@@ -23,7 +35,7 @@ class Paginator extends AbstractPaginator implements Arrayable, ArrayAccess, Cou
     /**
      * Create a new paginator instance.
      *
-     * @param  mixed  $items
+     * @param  TValue[]  $items
      * @param  int  $perPage
      * @param  int|null  $currentPage
      * @param  array  $options  (path, query, fragment, pageName)
@@ -60,7 +72,7 @@ protected function setCurrentPage($currentPage)
     /**
      * Set the items for the paginator.
      *
-     * @param  mixed  $items
+     * @param  Collection<TKey, TValue>|Arrayable<TKey, TValue>|iterable<TKey, TValue>|null  $items
      * @return void
      */
     protected function setItems($items)

tests/Pagination/PaginatorTest.php

@@ -9,6 +9,7 @@ class PaginatorTest extends TestCase
 {
     public function testSimplePaginatorReturnsRelevantContextInformation()
     {
+        /** @var Paginator<int, string> $p */
         $p = new Paginator(['item3', 'item4', 'item5'], 2, 2);
 
         $this->assertEquals(2, $p->currentPage());

types/Pagination/Paginator.php

@@ -0,0 +1,51 @@
+<?php
+
+use Illuminate\Pagination\CursorPaginator;
+use Illuminate\Pagination\LengthAwarePaginator;
+use Illuminate\Pagination\Paginator;
+
+use function PHPStan\Testing\assertType;
+
+$items = [new Post(), new Post(), new Post()];
+
+/** @var Paginator<int, Post> $paginator */
+$paginator = new Paginator($items, 1, 1);
+
+assertType('array<int, Post>', $paginator->items());
+assertType('ArrayIterator<int, Post>', $paginator->getIterator());
+
+$paginator->each(function ($post) {
+    assertType('Post', $post);
+});
+
+foreach ($paginator as $post) {
+    assertType('Post', $post);
+}
+
+/** @var LengthAwarePaginator<int, Post> $lengthAwarePaginator */
+$lengthAwarePaginator = new LengthAwarePaginator($items, 1, 1);
+
+assertType('array<int, Post>', $lengthAwarePaginator->items());
+assertType('ArrayIterator<int, Post>', $lengthAwarePaginator->getIterator());
+
+$lengthAwarePaginator->each(function ($post) {
+    assertType('Post', $post);
+});
+
+foreach ($lengthAwarePaginator as $post) {
+    assertType('Post', $post);
+}
+
+/** @var CursorPaginator<int, Post> $cursorPaginator */
+$cursorPaginator = new CursorPaginator($items, 1);
+
+assertType('array<int, Post>', $cursorPaginator->items());
+assertType('ArrayIterator<int, Post>', $cursorPaginator->getIterator());
+
+$cursorPaginator->each(function ($post) {
+    assertType('Post', $post);
+});
+
+foreach ($cursorPaginator as $post) {
+    assertType('Post', $post);
+}