Merge branch 'cleanup'

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/CurlerPageInterface.php

@@ -2,15 +2,34 @@
 
 namespace Salient\Contract\Curler;
 
+use Psr\Http\Message\RequestInterface;
+use OutOfRangeException;
+
 /**
  * @api
  */
-interface CurlerPageInterface extends CurlerPageRequestInterface
+interface CurlerPageInterface
 {
     /**
      * Get a list of entities returned by the endpoint
      *
      * @return list<mixed>
      */
     public function getEntities(): array;
+
+    /**
+     * Check if more data can be requested from the endpoint
+     */
+    public function hasNextRequest(): bool;
+
+    /**
+     * Get a request to retrieve the next page of data from the endpoint
+     *
+     * Return a {@see CurlerPageRequestInterface} to propagate query changes to
+     * the next {@see CurlerPagerInterface::getPage()} call in array form.
+     *
+     * @return CurlerPageRequestInterface|RequestInterface
+     * @throws OutOfRangeException if no more data can be requested.
+     */
+    public function getNextRequest();
 }

src/Toolkit/Contract/Curler/CurlerPageRequestInterface.php

@@ -3,30 +3,21 @@
 namespace Salient\Contract\Curler;
 
 use Psr\Http\Message\RequestInterface;
-use OutOfRangeException;
 
 /**
  * @api
  */
 interface CurlerPageRequestInterface
 {
     /**
-     * Check if a page of data can be retrieved from the endpoint
+     * Get a request to retrieve a page of data from the endpoint
      */
-    public function hasNextRequest(): bool;
+    public function getRequest(): RequestInterface;
 
     /**
-     * Get a request to retrieve the next page of data from the endpoint
-     *
-     * @throws OutOfRangeException if there are no more pages to retrieve.
-     */
-    public function getNextRequest(): RequestInterface;
-
-    /**
-     * Get the query applied to the request to retrieve the next page of data
+     * Get the query applied to the request to retrieve a page of data
      *
      * @return mixed[]|null
-     * @throws OutOfRangeException if there are no more pages to retrieve.
      */
-    public function getNextQuery(): ?array;
+    public function getQuery(): ?array;
 }

src/Toolkit/Contract/Curler/CurlerPagerInterface.php

@@ -15,6 +15,9 @@ interface CurlerPagerInterface
      *
      * Return `$request` if no special handling is required.
      *
+     * Return a {@see CurlerPageRequestInterface} to propagate `$query` changes
+     * to {@see CurlerPagerInterface::getPage()} in array form.
+     *
      * @param mixed[]|null $query The query applied to `$request`.
      * @return CurlerPageRequestInterface|RequestInterface
      */
@@ -27,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

@@ -376,11 +376,8 @@ private function process(string $method, ?array $query, $data = false)
         if ($pager) {
             $request = $pager->getFirstRequest($request, $this, $query);
             if ($request instanceof CurlerPageRequestInterface) {
-                if (!$request->hasNextRequest()) {
-                    throw new LogicException('No first request');
-                }
-                $query = $request->getNextQuery() ?? $query;
-                $request = $request->getNextRequest();
+                $query = $request->getQuery() ?? $query;
+                $request = $request->getRequest();
             }
         }
 
@@ -455,15 +452,12 @@ private function paginate(string $method, ?array $query, $data = false): Generat
 
         $request = $this->createRequest($method, $query, $data);
         $request = $this->Pager->getFirstRequest($request, $this, $query);
-        if ($request instanceof CurlerPageRequestInterface) {
-            if (!$request->hasNextRequest()) {
-                throw new LogicException('No first request');
-            }
-            $query = $request->getNextQuery() ?? $query;
-            $request = $request->getNextRequest();
-        }
         $prev = null;
         do {
+            if ($request instanceof CurlerPageRequestInterface) {
+                $query = $request->getQuery() ?? $query;
+                $request = $request->getRequest();
+            }
             $response = $this->doSendRequest($request);
             $page = $this->Pager->getPage(
                 $this->getResponseBody($response),
@@ -481,7 +475,6 @@ private function paginate(string $method, ?array $query, $data = false): Generat
             if (!$page->hasNextRequest()) {
                 break;
             }
-            $query = $page->getNextQuery() ?? $query;
             $request = $page->getNextRequest();
             $prev = $page;
         } while (true);
@@ -655,6 +648,14 @@ public function getPager(): ?CurlerPagerInterface
         return $this->Pager;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function alwaysPaginates(): bool
+    {
+        return $this->AlwaysPaginate;
+    }
+
     /**
      * @inheritDoc
      */
@@ -934,10 +935,8 @@ public function withoutMiddleware($middleware)
     /**
      * @inheritDoc
      */
-    public function withPager(
-        ?CurlerPagerInterface $pager,
-        bool $alwaysPaginate = false
-    ) {
+    public function withPager(?CurlerPagerInterface $pager, bool $alwaysPaginate = false)
+    {
         return $this
             ->with('Pager', $pager)
             ->with('AlwaysPaginate', $pager && $alwaysPaginate);

src/Toolkit/Curler/CurlerPage.php

@@ -57,29 +57,18 @@ public function getEntities(): array
      */
     public function hasNextRequest(): bool
     {
-        return $this->NextRequest !== null;
+        return (bool) $this->NextRequest;
     }
 
     /**
      * @inheritDoc
      */
-    public function getNextRequest(): RequestInterface
+    public function getNextRequest()
     {
-        if ($this->NextRequest === null) {
+        if (!$this->NextRequest) {
             throw new OutOfRangeException('No more pages');
         }
-        return $this->NextRequest->getNextRequest();
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function getNextQuery(): ?array
-    {
-        if ($this->NextRequest === null) {
-            throw new OutOfRangeException('No more pages');
-        }
-        return $this->NextRequest->getNextQuery();
+        return $this->NextRequest;
     }
 
     /**

src/Toolkit/Curler/CurlerPageRequest.php

@@ -32,23 +32,15 @@ public function __construct(
     /**
      * @inheritDoc
      */
-    public function hasNextRequest(): bool
-    {
-        return true;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    public function getNextRequest(): RequestInterface
+    public function getRequest(): RequestInterface
     {
         return $this->NextRequest;
     }
 
     /**
      * @inheritDoc
      */
-    public function getNextQuery(): ?array
+    public function getQuery(): ?array
     {
         return $this->NextQuery;
     }

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;