Merge pull request #5 from veewee/custom-pager

Use custom window-count based pager over pagerfanta

Author: veewee

README.md

@@ -608,6 +608,34 @@ App\Domain\Model\User:
               "id": !php/enum App\Infrastructure\Doctrine\Schema\User\UsersTableColumns::Id
 ```
 
+# Pagination
+
+Dealing with pagination is a task that is often needed.
+This package contains some tools to help you with that:
+
+```php
+use Phpro\DbalTools\Pager\MappingPager;
+use Phpro\DbalTools\Pager\Pager;
+use Phpro\DbalTools\Pager\Pagination;
+use Phpro\DbalTools\Pager\WindowCountPager;
+
+$query = $connection->createQueryBuilder()->select('*')->from('users');
+$userMapper = new UsersMapper()->convertFromDb(...);
+
+$usersPager = new MappingPager(
+    WindowCountPager::create(
+        new Pagination(page: $page limit: $limit),
+        $query,
+    ),
+    $userMapper,
+);
+
+// Iterating over the results:
+$totalResults = $usersPager->totalResults();
+$totalPages = $usersPager->totalPages();
+$users = [...$usersPager];
+```
+
 # Building queries
 
 This package contains a set of tools that helps you build queries based on partial SQL Expressions.

composer.json

@@ -31,9 +31,7 @@
         "symfony/translation": "^7.2",
         "symfony/validator": "^7.2",
         "doctrine/doctrine-migrations-bundle": "^3.4",
-        "doctrine/doctrine-bundle": "^2.14",
-        "pagerfanta/core": "^4.7",
-        "pagerfanta/doctrine-dbal-adapter": "^4.7"
+        "doctrine/doctrine-bundle": "^2.14"
     },
     "require-dev": {
         "phpunit/phpunit": "^12.1.3",
@@ -44,7 +42,8 @@
         "php-cs-fixer/shim": "^3.75",
         "phpro/grumphp-shim": "^2.12",
         "amphp/dns": "^2.4",
-        "amphp/socket": "^2.3.1"
+        "amphp/socket": "^2.3.1",
+        "ramsey/uuid": "^4.9"
     },
     "config": {
         "allow-plugins": {

src/Expression/Over.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Expression;
+
+final readonly class Over implements Expression
+{
+    public function __construct(
+        private ?Expression $expression,
+    ) {
+    }
+
+    public static function fullWindow(): self
+    {
+        return new self(null);
+    }
+
+    public static function partition(PartitionBy $partitionBy, ?OrderBy $orderBy = null): self
+    {
+        return new self(
+            Expressions::fromNullable($partitionBy, $orderBy)->join(' ')
+        );
+    }
+
+    public static function orderBy(OrderBy $orderBy): self
+    {
+        return new self($orderBy);
+    }
+
+    public static function aggregation(
+        Expression $aggregation,
+        self $over,
+    ): Expression {
+        return new Expressions($aggregation, $over)->join(' ');
+    }
+
+    public function toSQL(): string
+    {
+        return sprintf('OVER(%s)', $this->expression?->toSQL() ?? '');
+    }
+}

src/Expression/PartitionBy.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Expression;
+
+final readonly class PartitionBy implements Expression
+{
+    /**
+     * @no-named-arguments
+     */
+    public function __construct(
+        private Expression $partitionByExpression,
+    ) {
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function toSQL(): string
+    {
+        return sprintf('PARTITION BY %s', $this->partitionByExpression->toSQL());
+    }
+}

src/Expression/RowNumber.php

@@ -10,28 +10,18 @@
      * @no-named-arguments
      */
     public function __construct(
-        private ?Expression $expression = null,
+        private ?Over $over = null,
     ) {
     }
 
-    /**
-     * @no-named-arguments
-     */
-    public static function over(
-        Expression $expression,
-        Expression ...$expressions,
-    ): self {
-        return new self(new Expressions($expression, ...$expressions)->join(' '));
-    }
-
     /**
      * @return non-empty-string
      */
     public function toSQL(): string
     {
-        return sprintf(
-            'ROW_NUMBER() OVER (%s)',
-            $this->expression?->toSQL() ?? '',
-        );
+        return Over::aggregation(
+            new SqlExpression('ROW_NUMBER()'),
+            $this->over ?? Over::fullWindow(),
+        )->toSQL();
     }
 }

src/Pager/MappingPager.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Pager;
+
+use function Psl\Vec\map;
+
+/**
+ * @template I
+ * @template O
+ *
+ * @implements Pager<O>
+ */
+final readonly class MappingPager implements Pager
+{
+    /**
+     * @param Pager<I>       $pager
+     * @param \Closure(I): O $mapper
+     */
+    public function __construct(
+        private Pager $pager,
+        private \Closure $mapper,
+    ) {
+    }
+
+    public function pagination(): Pagination
+    {
+        return $this->pager->pagination();
+    }
+
+    public function totalResults(): int
+    {
+        return $this->pager->totalResults();
+    }
+
+    public function totalPages(): int
+    {
+        return $this->pager->totalPages();
+    }
+
+    public function traverse(\Closure $mapper): iterable
+    {
+        return map($this, $mapper);
+    }
+
+    public function getIterator(): \Traversable
+    {
+        foreach ($this->pager as $value) {
+            yield ($this->mapper)($value);
+        }
+    }
+}

src/Pager/MockedPager.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Pager;
+
+use function Psl\Math\ceil;
+use function Psl\Vec\map;
+
+/**
+ * @template T
+ *
+ * @template-implements Pager<T>
+ */
+final readonly class MockedPager implements Pager
+{
+    /**
+     * @param array<int, T> $records
+     */
+    public function __construct(
+        private Pagination $pagination,
+        private array $records,
+    ) {
+    }
+
+    public function pagination(): Pagination
+    {
+        return $this->pagination;
+    }
+
+    public function totalResults(): int
+    {
+        return count($this->records);
+    }
+
+    public function totalPages(): int
+    {
+        $totalResults = $this->totalResults();
+        $limit = $this->pagination()->limit;
+        if (!$totalResults) {
+            return 1;
+        }
+
+        return (int) ceil($this->totalResults() / $limit);
+    }
+
+    public function traverse(\Closure $mapper): iterable
+    {
+        return map($this, $mapper);
+    }
+
+    public function getIterator(): \Traversable
+    {
+        yield from array_slice(
+            $this->records,
+            ($this->pagination()->page - 1) * $this->pagination->limit,
+            $this->pagination()->limit
+        );
+    }
+}

src/Pager/Pager.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Pager;
+
+/**
+ * @template T
+ *
+ * @template-extends \IteratorAggregate<int, T>
+ */
+interface Pager extends \IteratorAggregate
+{
+    public function pagination(): Pagination;
+
+    public function totalResults(): int;
+
+    public function totalPages(): int;
+
+    /**
+     * @template O
+     *
+     * @param \Closure(T): O $mapper
+     *
+     * @return iterable<int, O>
+     */
+    public function traverse(\Closure $mapper): iterable;
+}

src/Pager/Pagination.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Phpro\DbalTools\Pager;
+
+final readonly class Pagination
+{
+    /**
+     * @param int<1,max> $page  - Page number, starting from 1
+     * @param int<1,max> $limit - Number of items per page
+     */
+    public function __construct(
+        public int $page,
+        public int $limit,
+    ) {
+    }
+}