Support paginations with current page in URI path

README.md

@@ -109,12 +109,18 @@ If the API uses a query parameter different from `page` to specify the current p
 LazyJsonPages::from($source)->pageName('current_page');
 ```
 
-Otherwise, if the number of the current page is present in the URI path - for example `https://example.com/users/1` - we can chain the method `pageInPath()`:
+Otherwise, if the number of the current page is present in the URI path - for example `https://example.com/users/page/1` - we can chain the method `pageInPath()`:
 
 ```php
 LazyJsonPages::from($source)->pageInPath();
 ```
 
+By default the last integer in the URI path is considered the page number. However we can customize the regular expression used to capture the page number, if need be:
+
+```php
+LazyJsonPages::from($source)->pageInPath('~/page/(\d+)$~');
+```
+
 Some API paginations may start with a page different from `1`. If that's the case, we can define the first page by chaining the method `firstPage()`:
 
 ```php

src/Concerns/ResolvesPages.php

@@ -2,6 +2,10 @@
 
 namespace Cerbero\LazyJsonPages\Concerns;
 
+use Cerbero\LazyJsonPages\Exceptions\InvalidPageInPathException;
+use GuzzleHttp\Psr7\Uri;
+use Psr\Http\Message\UriInterface;
+
 /**
  * The trait to resolve pages.
  */
@@ -17,20 +21,42 @@ protected function toPage(mixed $value, bool $onlyNumerics = true): string|int|n
         return match (true) {
             is_numeric($value) => (int) $value,
             !is_string($value) || $value === '' => null,
-            !($query = parse_url($value, PHP_URL_QUERY)) => $onlyNumerics ? null : $value,
-            default => $this->pageFromQuery($query, $onlyNumerics),
+            !$parsedUri = parse_url($value) => $onlyNumerics ? null : $value,
+            default => $this->pageFromParsedUri($parsedUri, $onlyNumerics),
         };
     }
 
     /**
-     * Retrieve the page from the given query.
+     * Retrieve the page from the given parsed URI.
      *
      * @return ($onlyNumerics is true ? int|null : string|int|null)
      */
-    protected function pageFromQuery(string $query, bool $onlyNumerics = true): string|int|null
+    protected function pageFromParsedUri(array $parsedUri, bool $onlyNumerics = true): string|int|null
     {
-        parse_str($query, $parameters);
+        if ($pattern = $this->config->pageInPath) {
+            preg_match($pattern, $parsedUri['path'] ?? '', $matches);
+
+            return $this->toPage($matches[1] ?? null, $onlyNumerics);
+        }
+
+        parse_str($parsedUri['query'] ?? '', $parameters);
 
         return $this->toPage($parameters[$this->config->pageName] ?? null, $onlyNumerics);
     }
+
+    /**
+     * Retrieve the URI for the given page.
+     */
+    protected function uriForPage(UriInterface $uri, string $page): UriInterface
+    {
+        if (!$pattern = $this->config->pageInPath) {
+            return Uri::withQueryValue($uri, $this->config->pageName, $page);
+        }
+
+        if (!preg_match($pattern, $path = $uri->getPath(), $matches, PREG_OFFSET_CAPTURE)) {
+            throw new InvalidPageInPathException($path, $pattern);
+        }
+
+        return $uri->withPath(substr_replace($path, $page, $matches[1][1], strlen($matches[1][0])));
+    }
 }

src/Concerns/SendsAsyncRequests.php

@@ -63,9 +63,7 @@ protected function yieldRequests(UriInterface $uri, array $pages): Generator
         $pages = $this->book->pullFailedPages() ?: $pages;
 
         foreach ($pages as $page) {
-            $pageUri = Uri::withQueryValue($uri, $this->config->pageName, (string) $page);
-
-            yield $page => $request->withUri($pageUri);
+            yield $page => $request->withUri($this->uriForPage($uri, (string) $page));
         }
     }
 }

src/Dtos/Config.php

@@ -11,6 +11,7 @@ final class Config
     public function __construct(
         public readonly string $pointer,
         public readonly string $pageName = 'page',
+        public readonly ?string $pageInPath = null,
         public readonly int $firstPage = 1,
         public readonly ?string $totalPagesKey = null,
         public readonly ?string $totalItemsKey = null,

src/Exceptions/InvalidPageInPathException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Cerbero\LazyJsonPages\Exceptions;
+
+/**
+ * The exception thrown when a page cannot be found in the URI path.
+ */
+class InvalidPageInPathException extends LazyJsonPagesException
+{
+    /**
+     * Instantiate the class.
+     */
+    public function __construct(public readonly string $path, public readonly string $pattern)
+    {
+        parent::__construct("The pattern [{$pattern}] could not capture any page from the path [{$path}].");
+    }
+}

src/LazyJsonPages.php

@@ -65,6 +65,16 @@ public function pageName(string $name): self
         return $this;
     }
 
+    /**
+     * Set the pattern to capture the page in the URI path.
+     */
+    public function pageInPath(string $pattern = '/(\d+)(?!.*\d)/'): self
+    {
+        $this->config['pageInPath'] = $pattern;
+
+        return $this;
+    }
+
     /**
      * Set the number of the first page.
      */

tests/Feature/StructureTest.php

@@ -0,0 +1,44 @@
+<?php
+
+use Cerbero\LazyJsonPages\Exceptions\InvalidPageInPathException;
+use Cerbero\LazyJsonPages\LazyJsonPages;
+
+it('supports paginations with the current page in the URI path', function () {
+    $expectedItems = require fixture('items.php');
+    $lazyCollection = LazyJsonPages::from('https://example.com/api/v1/users/page/1')
+        ->pageInPath()
+        ->totalPages('meta.total_pages')
+        ->collect('data.*');
+
+    expect($lazyCollection)->toLoadItemsViaRequests($expectedItems, [
+        'https://example.com/api/v1/users/page/1' => 'lengthAware/page1.json',
+        'https://example.com/api/v1/users/page/2' => 'lengthAware/page2.json',
+        'https://example.com/api/v1/users/page/3' => 'lengthAware/page3.json',
+    ]);
+});
+
+it('supports a custom pattern for paginations with the current page in the URI path', function () {
+    $expectedItems = require fixture('items.php');
+    $lazyCollection = LazyJsonPages::from('https://example.com/api/v1/users/page1')
+        ->pageInPath('~/page(\d+)$~')
+        ->totalPages('meta.total_pages')
+        ->collect('data.*');
+
+    expect($lazyCollection)->toLoadItemsViaRequests($expectedItems, [
+        'https://example.com/api/v1/users/page1' => 'lengthAware/page1.json',
+        'https://example.com/api/v1/users/page2' => 'lengthAware/page2.json',
+        'https://example.com/api/v1/users/page3' => 'lengthAware/page3.json',
+    ]);
+});
+
+it('fails if it cannot capture the current page in the URI path', function () {
+    $expectedItems = require fixture('items.php');
+    $lazyCollection = LazyJsonPages::from('https://example.com/users')
+        ->pageInPath()
+        ->totalPages('meta.total_pages')
+        ->collect('data.*');
+
+    expect($lazyCollection)->toLoadItemsViaRequests($expectedItems, [
+        'https://example.com/users' => 'lengthAware/page1.json',
+    ]);
+})->throws(InvalidPageInPathException::class, 'The pattern [/(\d+)(?!.*\d)/] could not capture any page from the path [/users].');