Finish up docs for v3

- Finish migration guide
- Add docs on the caching decorator
- Fix links + other minor alterations

Signed-off-by: George Steel <george@net-glue.co.uk>

Author: gsteel

docs/book/v3/application-integration/stand-alone.md

@@ -90,7 +90,7 @@ foreach ($paginator as $item) {
 }
 ```
 
-Retrieving the [current status data of the paginator](../usage.md#listing-of-properties):
+Retrieving the [current status data of the paginator](../usage.md#inspecting-paginator-state):
 
 ```php
 var_dump($paginator->getPages()->previous); // 1

docs/book/v3/caching.md

@@ -0,0 +1,107 @@
+# Caching paginator pages
+
+It is possible to cache pagination results by wrapping adapters in the shipped `CachingAdapter`.
+The `CachingAdapter` requires a pagination adapter, a PSR cache item pool and a unique cache-key prefix.
+
+```php
+use DateInterval;
+use Laminas\Paginator\Adapter\AdapterInterface;
+use Psr\Cache\CacheItemPoolInterface;
+
+final readonly class CachingAdapter implements AdapterInterface
+{
+    /**
+     * @param AdapterInterface<TKey, TValue> $adapter
+     * @param non-empty-string $cacheKeyPrefix
+     */
+    public function __construct(
+        private AdapterInterface $adapter,
+        private string $cacheKeyPrefix,
+        private CacheItemPoolInterface $cache,
+        private DateInterval|null $ttl,
+    ) {
+    }
+
+    // ...
+}
+```
+
+To _manually_ create a paginator that will cache results as they are retrieved, the following would be required:
+
+```php
+use Laminas\Paginator\Adapter\AdapterInterface;
+use Laminas\Paginator\Adapter\CachingAdapter;
+use Laminas\Paginator\Paginator;
+use Psr\Cache\CacheItemPoolInterface;
+
+$adapter = new \SpecialCustomAdapter(/** With some data that needs to be cached */);
+
+// Assume we have some ready-prepared objects:
+assert($cachePool instanceof CacheItemPoolInterface);
+assert($adapter instanceof AdapterInterface);
+
+$paginator = new Paginator(
+    new CachingAdapter(
+        $adapter,
+        'my-unique-prefix',
+        $cachePool,
+        new DateInterval('PT30M'),
+    ),
+    10,
+    10,
+    'Sliding',
+);
+```
+
+The above example assumes that `\SpecialCustomAdapter` is an adapter that makes expensive database calls or other I/O where caching is a useful performance improvement.
+
+The cache pool argument can be any [PSR-6](https://www.php-fig.org/psr/psr-6/) implementation.
+[laminas-cache](https://docs.laminas.dev/laminas-cache/v4/psr6/) provides a PSR-6 implementation along with [many other libraries](https://packagist.org/providers/psr/cache-implementation).
+
+Paginator assumes that you will likely use a single cache pool for all paginators, therefore a unique key prefix is required to prevent cache-key collisions with other paginator instances used elsewhere in your application.
+
+Finally, you can also provide an optional TTL in the form of a [`DateInterval`](https://www.php.net/manual/class.dateinterval.php) object.
+
+## `PaginatorFactory` integration and setting defaults
+
+The shipped `PaginatorFactory` class is capable of decorating adapters for you, providing some configuration is in-place, thereby reducing the previous example to:
+
+```php
+use Laminas\Paginator\PaginatorFactory;
+use Psr\Container\ContainerInterface;
+
+assert($container instanceof ContainerInterface);
+
+$adapter = new \SpecialCustomAdapter(/** With some data that needs to be cached */);
+
+$factory = $container->get(PaginatorFactory::class);
+$paginator = $factory->withCachingAdapter($adapter, 'my-unique-prefix');
+```
+
+Using the factory assumes that a single cache item pool will be used for all paginators _(Which is why the unique prefix is necessary)_.
+To take advantage of the paginator factory, you must ensure that you configure the necessary services.
+The following example assumes that you are using [Laminas Service Manager](https://docs.laminas.dev/laminas-servicemanager) for dependency injection.
+
+```php
+return [
+    // Laminas Service Manager Configuration:
+    'dependencies' => [
+        'factories' => [
+            'PaginatorCachePool' => \SomeFactoryThatWillProduceACacheItemPoolInterface::class,
+        ],
+    ],
+    
+    // Telling the paginator factory which "Service" to pull from the container:
+    'paginator' => [
+        'defaultCache' => 'PaginatorCachePool',
+        'defaultCacheTTL' => 'PT30M',
+    ],
+];
+```
+
+Further information:
+
+- [Custom Paginator Adapters](./advanced.md#custom-data-source-adapters)
+- [More information on writing factories with Laminas Service Manager](https://docs.laminas.dev/laminas-servicemanager/v4/configuring-the-service-manager/#factories)
+- [Using Laminas Cache as a PSR-6 Cache Pool](https://docs.laminas.dev/laminas-cache/v4/psr6/)
+- [The PSR-6 Specification](https://www.php-fig.org/psr/psr-6/)

docs/book/v3/migration/from-v2-to-v3.md

@@ -10,7 +10,7 @@ Version 3 of Laminas Paginator contains several backward incompatible changes.
 
 ### Re-worked, Optional Caching with `psr/cache`
 
-With the removal of caching from the paginator itself, it is now possible to decorate adapters as needed with the `CachingAdapter`:
+With the [removal of caching](#caching) from the paginator itself, it is now possible to decorate adapters as needed with the `CachingAdapter`:
 
 ```php
 use Laminas\Paginator\Adapter\ArrayAdapter;
@@ -26,7 +26,7 @@ $paginator = new Paginator(
 );
 ```
 
-[Further Documentation](CachingDocs)
+[Further Documentation](../caching.md)
 
 ## Bug Fixes & General Improvements
 
@@ -100,7 +100,7 @@ $json = json_encode($paginator->getCurrentItems());
 ### Removal of "Global Config" via Static Properties
 
 The method `Laminas\Paginator\Paginator::setGlobalConfig()` has been removed.
-To create pagers with consistent and centralised configuration defaults, use the [newly introduced `PaginatorFactory`](PagerFactory).
+To create pagers with consistent and centralised configuration defaults, use the [newly introduced `PaginatorFactory`](../configuration.md#the-paginator-factory-service).
 
 ### Removal of Unused Exception Types
 
@@ -118,7 +118,4 @@ It is possible to use the shipped `ConfigProvider` to ensure that the library is
 ### Removal of the `Factory` class
 
 The class `Laminas\Paginator\Factory` has been removed.
-Its conceptual functionality is replaced with the `Laminas\Paginator\PaginatorFactory` class which is [documented in detail here](PagerFactory).
-
-[PagerFactory]: ../does-not-exist-yet.md
-[CachingDocs]: ../does-not-exist-yet.md
+Its conceptual functionality is replaced with the `Laminas\Paginator\PaginatorFactory` class which is [documented in detail here](../configuration.md#the-paginator-factory-service).

docs/book/v3/usage.md

@@ -48,10 +48,10 @@ return [
 ];
 ```
 
-With the above route (and using [laminas-mvc](https://docs.laminas.dev/laminas-mvc/) controllers), you might set the current page number in your controller action like so:
+With the above route, in a [Mezzio](https://docs.mezzio.dev) application, you might set the current page number in your middleware like so:
 
 ```php
-$paginator->setCurrentPageNumber($this->params()->fromRoute('page'));
+$paginator->setCurrentPageNumber((int) $request->getAttribute('page'));
 ```
 
 Now we have a paginator filled with data, and the current page number is known, we can iterate over the paginated items:
@@ -277,3 +277,27 @@ $paginator->getPages(new ScrollingStyle());
 ```
 
 For further details on the other available options; see the [Configuration chapter](configuration.md).
+
+## Inspecting paginator state
+
+The paginator keeps track of its current position and provides a number of methods to retrieve information about its state:
+
+```php
+assert($pager instanceof Laminas\Paginator\Paginator);
+
+printf("The current page number is %d\n", $pager->getCurrentPageNumber());
+printf("The current page contains %d items\n", $pager->getCurrentItemCount());
+printf("In total there are %d items\n", $pager->getTotalItemCount());
+
+$pagesResult = $pager->getPages();
+
+printf("The first page number is %d\n", $pagesResult->first);
+printf("The first page number in range is %d\n", $pagesResult->firstPageInRange);
+printf("The last page number is %d\n", $pagesResult->last);
+printf("The last page number in range is %d\n", $pagesResult->lastPageInRange);
+printf("The next page number is %s\n", $pagesResult->next ?? 'NONE');
+printf("The previous page number is %s\n", $pagesResult->previous ?? 'NONE');
+printf("The total number of pages is %d\n", $pagesResult->pageCount);
+```
+
+The `Laminas\Paginator\Pages` value object retrieved from `$pager->getPages()` provides all the information needed to create a page navigation user interface.

mkdocs.yml

@@ -8,6 +8,7 @@ nav:
         - Usage: v3/usage.md
         - Configuration: v3/configuration.md
         - "Advanced Usage": v3/advanced.md
+        - "Caching Paged Result Sets": v3/caching.md
         - 'Application Integration':
             - 'Stand-Alone': v3/application-integration/stand-alone.md
         - 'Migration':