add: better pagination handling

- fix problem with next_cursor handling for database queries
- added raw extraction (->fillResult()) for 'has_more' and 'next_cursor' in EntityCollection (e.g. executed on querying databases)
- added ->offsetByResponse(...) for handling the offset based on the previous query result (query result = EntityCollection)
- added public functions for easy access to 'has_more' (->hasMoreEntries()) and 'next_cursor' (->nextCursor()) in EntityCollection

Author: johguentner

src/Endpoints/Database.php

@@ -2,6 +2,7 @@
 
 namespace FiveamCode\LaravelNotionApi\Endpoints;
 
+use FiveamCode\LaravelNotionApi\Entities\Collections\EntityCollection;
 use FiveamCode\LaravelNotionApi\Entities\Collections\PageCollection;
 use FiveamCode\LaravelNotionApi\Notion;
 use FiveamCode\LaravelNotionApi\Query\Filters\Filter;
@@ -66,7 +67,7 @@ public function query(): PageCollection
         } // TODO Compound filters!
 
         if ($this->startCursor !== null) {
-            $postData['start_cursor'] = $this->startCursor;
+            $postData['start_cursor'] = $this->startCursor->__toString();
         }
 
         if ($this->pageSize !== null) {
@@ -104,4 +105,15 @@ public function sortBy(Collection $sorts): Database
 
         return $this;
     }
+
+    /**
+     * @param EntityCollection $entityCollection
+     * @return $this
+     */
+    public function offsetByResponse(EntityCollection $entityCollection): Database
+    {
+        $this->offset($entityCollection->nextCursor());
+
+        return $this;
+    }
 }

src/Entities/Collections/EntityCollection.php

@@ -7,6 +7,7 @@
 use FiveamCode\LaravelNotionApi\Entities\Page;
 use FiveamCode\LaravelNotionApi\Exceptions\HandlingException;
 use FiveamCode\LaravelNotionApi\Exceptions\NotionException;
+use FiveamCode\LaravelNotionApi\Query\StartCursor;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 
@@ -25,6 +26,16 @@ class EntityCollection
      */
     protected array $rawResults = [];
 
+    /**
+     * @var bool
+     */
+    protected bool $hasMore = false;
+
+    /**
+     * @var string
+     */
+    protected ?string $nextCursor = null;
+
     /**
      * @var Collection
      */
@@ -96,13 +107,24 @@ protected function collectChildren(): void
     protected function fillFromRaw()
     {
         $this->fillResult();
+        $this->fillCursorInformation();
     }
 
     protected function fillResult()
     {
         $this->rawResults = $this->responseData['results'];
     }
 
+    protected function fillCursorInformation()
+    {
+        if (Arr::exists($this->responseData, 'has_more')) {
+            $this->hasMore = $this->responseData['has_more'];
+        }
+        if (Arr::exists($this->responseData, 'next_cursor')) {
+            $this->nextCursor = $this->responseData['next_cursor'];
+        }
+    }
+
     /**
      * @return array
      */
@@ -111,6 +133,14 @@ public function getRawResponse(): array
         return $this->responseData;
     }
 
+    /**
+     * @return string
+     */
+    public function getRawNextCursor(): ?string
+    {
+        return $this->nextCursor;
+    }
+
     /**
      * @return Collection
      */
@@ -128,4 +158,20 @@ public function asJson(): string
             return $item->toArray();
         });
     }
+
+    /**
+     * @return bool
+     */
+    public function hasMoreEntries(): bool
+    {
+        return $this->hasMore;
+    }
+
+    /**
+     * @return StartCursor
+     */
+    public function nextCursor(): StartCursor
+    {
+        return new StartCursor($this->getRawNextCursor());
+    }
 }