Merge tag 'v2.1.0' into develop

Support encoded ids.

Author: lindyhopchris

CHANGELOG.md

@@ -9,6 +9,20 @@ All notable changes to this project will be documented in this file. This projec
 
 - Upgrade to Laravel 10 and set minimum PHP version to 8.1.
 
+## [2.1.0] - 2023-01-24
+
+### Added
+
+- The cursor pagination implementation now supports id fields that are encoded. To use, pass your schema's id
+  field to the cursor pagination class when returning it from the schema's `pagination()` method. For example:
+
+```php
+public function pagination(): CursorPagination
+{
+    return CursorPagination::make($this->id());
+}
+```
+
 ## [2.0.0] - 2022-02-09
 
 ### Added

src/Cursor/Cursor.php

@@ -113,5 +113,4 @@ public function getLimit(): ?int
     {
         return $this->limit;
     }
-
 }

src/Cursor/CursorBuilder.php

@@ -24,8 +24,11 @@
 use Illuminate\Database\Eloquent\Relations\Relation;
 use Illuminate\Database\Query\Builder as QueryBuilder;
 use InvalidArgumentException;
+use LaravelJsonApi\Contracts\Schema\ID;
+use LaravelJsonApi\Core\Schema\IdParser;
 use LogicException;
 use OutOfRangeException;
+use RuntimeException;
 use function in_array;
 
 class CursorBuilder
@@ -36,6 +39,11 @@ class CursorBuilder
      */
     private $query;
 
+    /**
+     * @var ID|null
+     */
+    private ?ID $id = null;
+
     /**
      * @var string
      */
@@ -81,6 +89,17 @@ public function __construct($query, string $column = null, string $key = null)
         $this->direction = 'desc';
     }
 
+    /**
+     * @param ID|null $id
+     * @return $this
+     */
+    public function withIdField(?ID $id): self
+    {
+        $this->id = $id;
+
+        return $this;
+    }
+
     /**
      * Set the query direction.
      *
@@ -178,7 +197,8 @@ private function getQualifiedKeyName(): string
     private function next(Cursor $cursor, $columns): CursorPaginator
     {
         if ($cursor->isAfter()) {
-            $this->whereId($cursor->getAfter(), $this->isDescending() ? '<' : '>');
+            $afterId = $this->decodeId($cursor->getAfter());
+            $this->whereId($afterId, $this->isDescending() ? '<' : '>');
         }
 
         $items = $this
@@ -187,12 +207,15 @@ private function next(Cursor $cursor, $columns): CursorPaginator
 
         $more = $items->count() > $cursor->getLimit();
 
-        return new CursorPaginator(
+        $paginator = new CursorPaginator(
             $items->slice(0, $cursor->getLimit()),
             $more,
             $cursor,
             $this->getUnqualifiedKey()
         );
+        $paginator->withIdField($this->id);
+
+        return $paginator;
     }
 
     /**
@@ -212,14 +235,36 @@ private function next(Cursor $cursor, $columns): CursorPaginator
      */
     private function previous(Cursor $cursor, $columns): CursorPaginator
     {
+        $beforeId = $this->decodeId($cursor->getBefore());
+
         $items = $this
-            ->whereId($cursor->getBefore(), $this->isDescending() ? '>' : '<')
+            ->whereId($beforeId, $this->isDescending() ? '>' : '<')
             ->orderForPrevious()
             ->get($cursor->getLimit(), $columns)
             ->reverse()
             ->values();
 
-        return new CursorPaginator($items, true, $cursor, $this->getUnqualifiedKey());
+        $paginator = new CursorPaginator($items, true, $cursor, $this->getUnqualifiedKey());
+        $paginator->withIdField($this->id);
+
+        return $paginator;
+    }
+
+    /**
+     * @param int|string $id
+     * @return int|string
+     */
+    private function decodeId($id)
+    {
+        $decoded = IdParser::make($this->id)->decodeIfMatch($id);
+
+        if (null === $decoded) {
+            throw new RuntimeException(
+                "Cursor key {$id} did not decode. Use validation to ensure the key matches the expected pattern."
+            );
+        }
+
+        return $decoded;
     }
 
     /**

src/Cursor/CursorPaginator.php

@@ -23,6 +23,8 @@
 use Illuminate\Database\Eloquent\Collection as EloquentCollection;
 use Illuminate\Pagination\Paginator;
 use IteratorAggregate;
+use LaravelJsonApi\Contracts\Schema\ID;
+use LaravelJsonApi\Core\Schema\IdParser;
 use LogicException;
 use Traversable;
 
@@ -54,6 +56,11 @@ class CursorPaginator implements IteratorAggregate, Countable
      */
     private ?string $path;
 
+    /**
+     * @var ID|null
+     */
+    private ?ID $id = null;
+
     /**
      * CursorPaginator constructor.
      *
@@ -72,6 +79,17 @@ public function __construct(EloquentCollection $items, bool $more, Cursor $curso
         $this->key = $key;
     }
 
+    /**
+     * @param ID|null $id
+     * @return $this
+     */
+    public function withIdField(?ID $id): self
+    {
+        $this->id = $id;
+
+        return $this;
+    }
+
     /**
      * @return EloquentCollection
      */
@@ -86,7 +104,9 @@ public function getItems(): EloquentCollection
     public function firstItem()
     {
         if ($first = $this->items->first()) {
-            return $first->{$this->key};
+            return IdParser::make($this->id)->encode(
+                $first->{$this->key},
+            );
         }
 
         return null;
@@ -98,7 +118,9 @@ public function firstItem()
     public function lastItem()
     {
         if ($last = $this->items->last()) {
-            return $last->{$this->key};
+            return IdParser::make($this->id)->encode(
+                $last->{$this->key},
+            );
         }
 
         return null;

src/CursorPagination.php

@@ -21,16 +21,21 @@
 
 use InvalidArgumentException;
 use LaravelJsonApi\Contracts\Pagination\Page;
+use LaravelJsonApi\Contracts\Schema\ID;
 use LaravelJsonApi\Core\Pagination\Concerns\HasPageMeta;
 use LaravelJsonApi\CursorPagination\Cursor\Cursor;
 use LaravelJsonApi\CursorPagination\Cursor\CursorBuilder;
 use LaravelJsonApi\Eloquent\Contracts\Paginator;
 
 class CursorPagination implements Paginator
 {
-
     use HasPageMeta;
 
+    /**
+     * @var ID|null
+     */
+    private ?ID $id;
+
     /**
      * @var string
      */
@@ -74,18 +79,22 @@ class CursorPagination implements Paginator
     /**
      * Fluent constructor.
      *
+     * @param ID|null $id
      * @return CursorPagination
      */
-    public static function make(): self
+    public static function make(ID $id = null): self
     {
-        return new static();
+        return new static($id);
     }
 
     /**
-     * CursorStrategy constructor.
+     * CursorPagination constructor.
+     *
+     * @param ID|null $id
      */
-    public function __construct()
+    public function __construct(ID $id = null)
     {
+        $this->id = $id;
         $this->before = 'before';
         $this->after = 'after';
         $this->limit = 'limit';
@@ -223,6 +232,7 @@ public function paginate($query, array $page): Page
     {
         $paginator = $this
             ->query($query)
+            ->withIdField($this->id)
             ->withDirection($this->direction)
             ->withDefaultPerPage($this->defaultPerPage)
             ->paginate($this->cursor($page), $this->columns ?: ['*']);