Sync: Improve support for Curler's "always paginate" option

- Add `HttpSyncProvider::getAlwaysPaginate()` method
- Add `$alwaysPaginate` parameter to `HttpSyncProvider::getCurler()`
- Add `HttpSyncDefinition::$AlwaysPaginate` property
- Add `$alwaysPaginate` parameter to `HttpSyncDefinition::withPager()`
  for consistency with the equivalent `Curler` method
- Fix incorrect documentation re: `HttpSyncProvider::getCurler()`
  arguments taking precedence over `HttpSyncProvider::filterCurler()`

Author: lkrms

src/Toolkit/Curler/Curler.php

@@ -935,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/Sync/Http/HttpSyncDefinition.php

@@ -65,6 +65,7 @@
  * @property-read mixed[]|null $Query Query parameters applied to the sync operation URL
  * @property-read HttpHeadersInterface|null $Headers HTTP headers applied to the sync operation request
  * @property-read CurlerPagerInterface|null $Pager Pagination handler for the endpoint servicing the entity
+ * @property-read bool $AlwaysPaginate Use the pager to process requests even if no pagination is required
  * @property-read int<-1,max>|null $Expiry Seconds before cached responses expire
  * @property-read array<OP::*,HttpRequestMethod::*> $MethodMap Array that maps sync operations to HTTP request methods
  * @property-read (callable(CurlerInterface, HttpSyncDefinition<TEntity,TProvider>, OP::*, SyncContextInterface, mixed...): CurlerInterface)|null $CurlerCallback Callback applied to the Curler instance created to perform each sync operation
@@ -156,6 +157,11 @@ final class HttpSyncDefinition extends AbstractSyncDefinition implements Buildab
      */
     protected ?CurlerPagerInterface $Pager;
 
+    /**
+     * Use the pager to process requests even if no pagination is required
+     */
+    protected bool $AlwaysPaginate;
+
     /**
      * Seconds before cached responses expire
      *
@@ -251,6 +257,7 @@ public function __construct(
         ?array $query = null,
         ?HttpHeadersInterface $headers = null,
         ?CurlerPagerInterface $pager = null,
+        bool $alwaysPaginate = false,
         ?callable $callback = null,
         $conformity = ListConformity::NONE,
         ?int $filterPolicy = null,
@@ -286,6 +293,7 @@ public function __construct(
         $this->Query = $query;
         $this->Headers = $headers;
         $this->Pager = $pager;
+        $this->AlwaysPaginate = $pager && $alwaysPaginate;
         $this->Callback = $callback;
         $this->Expiry = $expiry;
         $this->MethodMap = $methodMap;
@@ -331,11 +339,15 @@ public function withHeaders(?HttpHeadersInterface $headers)
     /**
      * Get an instance with the given pagination handler
      *
+     * @param bool $alwaysPaginate If `true`, the pager is used to process
+     * requests even if no pagination is required.
      * @return static
      */
-    public function withPager(?CurlerPagerInterface $pager)
+    public function withPager(?CurlerPagerInterface $pager, bool $alwaysPaginate = false)
     {
-        return $this->with('Pager', $pager);
+        return $this
+            ->with('Pager', $pager)
+            ->with('AlwaysPaginate', $pager && $alwaysPaginate);
     }
 
     /**
@@ -716,7 +728,13 @@ private function doRunHttpOperation($operation, SyncContextInterface $ctx, ...$a
             );
         }
 
-        $curler = $this->Provider->getCurler($path, $this->Expiry, $this->Headers, $this->Pager);
+        $curler = $this->Provider->getCurler(
+            $path,
+            $this->Expiry,
+            $this->Headers,
+            $this->Pager,
+            $this->AlwaysPaginate,
+        );
 
         if ($this->CurlerCallback) {
             $curler = ($this->CurlerCallback)($curler, $this, $operation, $ctx, ...$args);
@@ -867,6 +885,7 @@ public static function getReadableProperties(): array
             'Query',
             'Headers',
             'Pager',
+            'AlwaysPaginate',
             'Expiry',
             'MethodMap',
             'CurlerCallback',

src/Toolkit/Sync/Http/HttpSyncDefinitionBuilder.php

@@ -30,19 +30,21 @@ abstract class HttpSyncProvider extends AbstractSyncProvider
      * expire, or:
      * - `null`: do not cache responses
      * - `0`: cache responses indefinitely
-     * - `-1` (default): use the value returned by {@see getExpiry()}
+     * - `-1` (default): use value returned by {@see getExpiry()}
      */
     final public function getCurler(
         string $path,
         ?int $expiry = -1,
         ?HttpHeadersInterface $headers = null,
         ?CurlerPagerInterface $pager = null,
+        bool $alwaysPaginate = false,
         ?DateFormatterInterface $dateFormatter = null
     ): CurlerInterface {
         $builder = Curler::build()
             ->uri($this->getEndpointUrl($path))
             ->headers($headers ?? $this->getHeaders($path))
             ->pager($pager ?? $this->getPager($path))
+            ->alwaysPaginate($pager ? $alwaysPaginate : $this->getAlwaysPaginate($path))
             ->dateFormatter($dateFormatter ?? $this->getDateFormatter());
 
         if ($expiry === -1) {
@@ -100,6 +102,17 @@ protected function getPager(string $path): ?CurlerPagerInterface
         return null;
     }
 
+    /**
+     * Override if the pager returned by getPager() should be used to process
+     * requests even if no pagination is required
+     *
+     * @codeCoverageIgnore
+     */
+    protected function getAlwaysPaginate(string $path): bool
+    {
+        return false;
+    }
+
     /**
      * Override to specify the number of seconds before cached responses from
      * the upstream API expire
@@ -118,8 +131,8 @@ protected function getExpiry(string $path): ?int
      * Override to customise Curler instances before they are used to perform
      * sync operations
      *
-     * Values passed to {@see HttpSyncProvider::getCurler()} take precedence
-     * over values applied by this method.
+     * Values passed to {@see HttpSyncProvider::getCurler()} are applied before
+     * this method is called.
      *
      * @codeCoverageIgnore
      */