Add OffsetPaginator and align CursorPaginator on an immutable page API

Author: seb-jean

UPGRADE.md

@@ -29,6 +29,38 @@ and directly start using native lazy objects.
 
 # Upgrade to 3.7
 
+## Deprecated `Doctrine\ORM\Tools\Pagination\Paginator`
+
+Use `Doctrine\ORM\Tools\Pagination\OffsetPaginator` instead. The offset is no
+longer read implicitly from the query: it is passed as an `Offset` value object
+to `paginate()`, which returns an immutable, iterable `OffsetPage`.
+
+```diff
+-use Doctrine\ORM\Tools\Pagination\Paginator;
++use Doctrine\ORM\Tools\Pagination\Offset;
++use Doctrine\ORM\Tools\Pagination\OffsetPaginator;
+
+-$query = $entityManager->createQuery($dql)
+-    ->setFirstResult(0)
+-    ->setMaxResults(25);
++$query = $entityManager->createQuery($dql);
+
+-$paginator = new Paginator($query, fetchJoinCollection: true);
++$page = (new OffsetPaginator(fetchJoinCollection: true))
++    ->paginate($query, new Offset(0, 25));
+
+-$total = count($paginator);
++$total = $page->getTotalCount();
+
+-foreach ($paginator as $post) {
++foreach ($page as $post) {
+     // ...
+ }
+```
+
+`Paginator::setUseOutputWalkers()` becomes the `useOutputWalkers` constructor
+argument of `OffsetPaginator`.
+
 ## Deprecated `Doctrine\ORM\Query\AST\TypedExpression`
 
 Implement `Doctrine\ORM\Query\AST\ExpressionWithReturnType` instead, which exposes