Curler: Add TPage template to CurlerPagerInterface::getPage()

- Add `CurlerInterface::alwaysPaginates()`
- Simplify built-in pagers after recent interface improvements

Author: lkrms

src/Toolkit/Contract/Curler/CurlerInterface.php

@@ -463,6 +463,12 @@ public function withoutMiddleware($middleware);
      */
     public function getPager(): ?CurlerPagerInterface;
 
+    /**
+     * Check if the endpoint's pagination handler is used to process every
+     * request
+     */
+    public function alwaysPaginates(): bool;
+
     /**
      * Get an instance with the given pagination handler
      *

src/Toolkit/Contract/Curler/CurlerPagerInterface.php

@@ -30,9 +30,13 @@ public function getFirstRequest(
     /**
      * Convert data returned by the endpoint to a new page object
      *
+     * @template TPage of CurlerPageInterface|null
+     *
      * @param mixed $data
+     * @param TPage $previousPage
      * @param mixed[]|null $query The query applied to `$request` or returned by
      * {@see CurlerPageRequestInterface::getNextQuery()}, if applicable.
+     * @return (TPage is null ? CurlerPageInterface : TPage)
      */
     public function getPage(
         $data,

src/Toolkit/Curler/Curler.php

@@ -648,6 +648,14 @@ public function getPager(): ?CurlerPagerInterface
         return $this->Pager;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function alwaysPaginates(): bool
+    {
+        return $this->AlwaysPaginate;
+    }
+
     /**
      * @inheritDoc
      */

src/Toolkit/Curler/Pager/LinkPager.php

@@ -9,12 +9,13 @@
 use Salient\Contract\Http\HttpHeader;
 use Salient\Contract\Http\HttpResponseInterface;
 use Salient\Curler\CurlerPage;
+use Salient\Curler\CurlerPageRequest;
 use Salient\Http\Http;
 use Salient\Http\Uri;
 use Closure;
 
 /**
- * Follows "Link" headers in responses from the endpoint
+ * Follows "Link" headers with rel="next" in responses from the endpoint
  *
  * @api
  */
@@ -54,16 +55,16 @@ public function getFirstRequest(
         RequestInterface $request,
         CurlerInterface $curler,
         ?array $query = null
-    ): RequestInterface {
+    ) {
         if ($this->PageSize === null) {
             return $request;
         }
 
         $query[$this->PageSizeKey] = $this->PageSize;
-        $uri = $request->getUri();
-        $uri = $curler->replaceQuery($uri, $query);
-
-        return $request->withUri($uri);
+        return new CurlerPageRequest(
+            $curler->replaceQuery($request, $query),
+            $query,
+        );
     }
 
     /**
@@ -79,18 +80,15 @@ public function getPage(
     ): CurlerPageInterface {
         $data = ($this->EntitySelector)($data);
 
-        $response = $curler->getLastResponse();
-        if ($response && ($links = $response->getHeaderValues(HttpHeader::LINK))) {
-            foreach ($links as $link) {
-                /** @var array{string,rel?:string} */
-                $link = Http::getParameters($link);
-                if (($link['rel'] ?? null) === 'next') {
-                    $link = trim($link[0], '<>');
-                    $uri = $request->getUri();
-                    $uri = Uri::from($uri)->follow($link);
-                    $nextRequest = $request->withUri($uri);
-                    break;
-                }
+        foreach ($response->getHeaderValues(HttpHeader::LINK) as $link) {
+            /** @var array{string,rel?:string} */
+            $link = Http::getParameters($link);
+            if (($link['rel'] ?? null) === 'next') {
+                $link = trim($link[0], '<>');
+                $uri = $request->getUri();
+                $uri = Uri::from($uri)->follow($link);
+                $nextRequest = $request->withUri($uri);
+                break;
             }
         }
 

src/Toolkit/Curler/Pager/ODataPager.php

@@ -73,8 +73,7 @@ public function getPage(
             throw new InvalidArgumentTypeException(1, 'data', 'mixed[]', $data);
         }
         /** @var array{'@odata.nextLink'?:string,'@nextLink'?:string,value:list<mixed>,...} $data */
-        $response = $curler->getLastResponse();
-        if ($response && $response->getHeaderLine(HttpHeader::ODATA_VERSION) === '4.0') {
+        if ($response->getHeaderLine(HttpHeader::ODATA_VERSION) === '4.0') {
             $nextLink = $data['@odata.nextLink'] ?? null;
         } else {
             $nextLink = $data['@nextLink'] ?? $data['@odata.nextLink'] ?? null;

src/Toolkit/Curler/Pager/QueryPager.php

@@ -8,7 +8,9 @@
 use Salient\Contract\Curler\CurlerPagerInterface;
 use Salient\Contract\Http\HttpResponseInterface;
 use Salient\Curler\CurlerPage;
+use Salient\Utility\Test;
 use Closure;
+use LogicException;
 
 /**
  * Increments a value in the query string of each request until no results are
@@ -22,11 +24,8 @@ final class QueryPager implements CurlerPagerInterface
 
     /** @var array-key|null */
     private $PageKey;
+    /** @var int<1,max>|null */
     private ?int $PageSize;
-    /** @var mixed[] */
-    private array $CurrentQuery;
-    /** @var array-key|null */
-    private $CurrentPageKey;
 
     /**
      * Creates a new QueryPager object
@@ -40,10 +39,9 @@ final class QueryPager implements CurlerPagerInterface
      * - `Arr::get($data, $entitySelector)` if `$entitySelector` is a string or
      *   integer, or
      * - `$data` if `$entitySelector` is `null`
-     * @param int|null $pageSize Another page is requested if:
+     * @param int<1,max>|null $pageSize Another page is requested if:
      * - `$pageSize` is `null` and at least one result is returned, or
-     * - `$pageSize` is greater than `0` and exactly `$pageSize` results are
-     *   returned
+     * - exactly `$pageSize` results are returned
      */
     public function __construct(
         $pageKey = null,
@@ -63,18 +61,6 @@ public function getFirstRequest(
         CurlerInterface $curler,
         ?array $query = null
     ): RequestInterface {
-        $this->CurrentQuery = $query ?? [];
-        $this->CurrentPageKey = null;
-
-        // If `$this->PageKey` does not appear in the query, add it to
-        // `$this->CurrentQuery` without changing the first request
-        if (
-            $this->PageKey !== null
-            && !array_key_exists($this->PageKey, $this->CurrentQuery)
-        ) {
-            $this->CurrentQuery[$this->PageKey] = 1;
-        }
-
         return $request;
     }
 
@@ -93,26 +79,20 @@ public function getPage(
 
         if ($data && (
             $this->PageSize === null
-            || $this->PageSize < 1
             || count($data) === $this->PageSize
         )) {
-            if (
-                $this->PageKey === null
-                && !$previousPage
-                && $this->CurrentQuery
-                && is_int(reset($this->CurrentQuery))
-            ) {
-                $this->CurrentPageKey = key($this->CurrentQuery);
+            $key = $this->PageKey;
+            if ($key === null && $query && Test::isInteger(reset($query))) {
+                $key = key($query);
             }
-            $key = $this->PageKey ?? $this->CurrentPageKey;
-            if ($key !== null) {
-                $this->CurrentQuery[$key]++;
-                $uri = $request->getUri();
-                $uri = $curler->replaceQuery($uri, $this->CurrentQuery);
-                $nextRequest = $request->withUri($uri);
+            if ($key === null) {
+                throw new LogicException('No page key and no integer value at query offset 0');
             }
+            $query[$key] ??= 1;
+            $query[$key]++;
+            $nextRequest = $curler->replaceQuery($request, $query);
         }
 
-        return new CurlerPage($data, $nextRequest ?? null);
+        return new CurlerPage($data, $nextRequest ?? null, $query);
     }
 }

tests/fixtures/Toolkit/Sync/Provider/MockoonPager.php

@@ -22,7 +22,7 @@ public function getFirstRequest(
         $query['limit'] ??= 50;
         unset($query['page']);
         return new CurlerPageRequest(
-            $request->withUri($curler->replaceQuery($request->getUri(), $query)),
+            $curler->replaceQuery($request, $query),
             $query,
         );
     }
@@ -49,7 +49,7 @@ public function getPage(
             /** @var array{page?:int} $query */
             $query['page'] ??= 1;
             $query['page']++;
-            $nextRequest = $request->withUri($curler->replaceQuery($request->getUri(), $query));
+            $nextRequest = $curler->replaceQuery($request, $query);
         }
 
         return new CurlerPage($data, $nextRequest ?? null, $query, $count, $total);