Merge pull request #92 from gsteel/v3/migration-guide

Finish Migration Guide, Caching Docs and v3 Release Preparation

Author: gsteel

Makefile

@@ -139,11 +139,11 @@ unused-ci: vendor/bin/composer-unused
 
 rector: ## Run Rector and show the diff
 	@$(call MK_INFO,"Checking for syntax consistency with rector")
-	@docker run $(DOCKER_PHP) tools/rector/vendor/bin/rector process --dry-run -vv -c tools/rector/rector.php
+	@docker run $(DOCKER_PHP) tools/rector/vendor/bin/rector process --dry-run -c tools/rector/rector.php
 .PHONY: rector
 
 rector-ci: ## Run Rector and show the diff in GitHub format for CI
-	tools/rector/vendor/bin/rector process --dry-run --output-format=github -vv -c tools/rector/rector.php
+	tools/rector/vendor/bin/rector process --dry-run --output-format=github -c tools/rector/rector.php
 .PHONY: rector
 
 rector-fix: ## Apply Rector changes

composer.json

@@ -39,8 +39,8 @@
         "laminas/laminas-cache": "^4.1",
         "laminas/laminas-cache-storage-adapter-memory": "^3.1",
         "laminas/laminas-coding-standard": "^3.1.0",
-        "lcobucci/clock": "^3.3",
-        "phpunit/phpunit": "^11.5.43",
+        "lcobucci/clock": "^3.3.1",
+        "phpunit/phpunit": "^11.5.45",
         "psalm/plugin-phpunit": "^0.19.5",
         "vimeo/psalm": "^6.13.1"
     },

composer.lock

@@ -49,8 +49,6 @@ Take a look at the packaged adapters for ideas of how you might go about impleme
 
 ### Registering Your Adapter with the Plugin Manager
 
-> Available since version 2.10.0.
-
 If you want to register your adapter with the `Laminas\Pagiantor\AdapterPluginManager`, you can do so via configuration.
 The "paginators" configuration key can contain [standard laminas-servicemanager-style configuration](https://docs.laminas.dev/laminas-servicemanager/configuring-the-service-manager/).
 

docs/book/v3/advanced.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/application-integration/stand-alone.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/caching.md

@@ -0,0 +1,121 @@
+# Migrating from Version 2 to Version 3
+
+Version 3 of Laminas Paginator contains several backward incompatible changes.
+
+## New Features
+
+### Laminas Service Manager v4 Support
+
+`laminas-paginator` new requires `laminas-servicemanager` version 4, therefore allowing `psr/container` 2.0 installation.
+
+### Re-worked, Optional Caching with `psr/cache`
+
+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;
+use Laminas\Paginator\Adapter\CachingAdapter;
+use Laminas\Paginator\Paginator;
+
+$paginator = new Paginator(
+    new CachingAdapter(
+        new ArrayAdapter($someData),
+        'my-unique-prefix',
+        $someCacheItemPoolInterface,
+    ),
+);
+```
+
+[Further Documentation](../caching.md)
+
+## Bug Fixes & General Improvements
+
+- Native parameter, property and return types have been added throughout the code base
+- It is now possible to paginate associative arrays, or any type of iterable with string keys. Type inference for keys and values is retained.
+- Type inference has been drastically improved for a more convenient developer experience. We strongly suggest usage of Psalm or PHPStan to benefit from these improvements.
+
+## Feature Removal
+
+### Caching
+
+The caching features of the main Paginator class have been removed.
+This means the following constants and methods of `Laminas\Paginator\Paginator` no longer exist:
+
+- `CACHE_TAG_PREFIX` constant
+- `setCache()`
+- `setCacheEnabled()`
+- `clearPageItemCache()`
+- `getPageItemCache()`
+- `cacheEnabled()`
+
+### `laminas-view` integration
+
+`Laminas\Paginator\Paginator` was unnecessarily, tightly coupled to Laminas View.
+Because paginator is conceptually independent of a specific templating implementation, expect stand-alone integrations in the future.
+The removal of Laminas view integration resulted in the following changes to `Laminas\Paginator\Paginator`:
+
+- `Laminas\Paginator\Paginator` no longer implements the `Stringable` interface
+- The following methods have been removed:
+    - `__toString()`
+    - `getView()`
+    - `setView()`
+    - `render()`
+
+### Removal of Un-documented Filtering Feature
+
+Previously, paginator allowed users to provide a `Laminas\Filter\FilterInterface` that would be used to filter/mutate the result set returned by adapters.
+This feature has been removed.
+It is unlikely the feature was widely used, and it had questionable merit because it would break the guarantees that a page of 10 items, would indeed contain 10 items.
+
+The following methods have been removed from `Laminas\Paginator\Paginator`:
+
+- `getFilter()`
+- `setFilter()`
+
+### Removal of the `ScrollingStylePluginManager`
+
+Generally speaking, scrolling styles are relatively simple computations.
+They can easily be "newed" when required.
+You can still refer to them by 'name', for example _'Sliding'_.
+
+Along with the plugin manger, a number of static methods associated with scrolling styles were removed from `Laminas\Paginator\Paginator`:
+
+- `getDefaultScrollingStyle()`
+- `setDefaultScrollingStyle()`
+- `getDefaultItemCountPerPage()`
+- `setDefaultItemCountPerPage()`
+- `setScrollingStylePluginManager()`
+- `getScrollingStylePluginManager()`
+
+### Json encoding of Paginator Result Sets
+
+The method `Laminas\Paginator\Paginator::toJson()` has been removed.
+It is not a paginators concern to encode the paged items to any format.
+If you relied on this functionality, it can be reproduced by encoding the current items yourself with `json_encode`, for example:
+
+```php
+$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`](../configuration.md#the-paginator-factory-service).
+
+### Removal of Unused Exception Types
+
+The following exceptions no longer exist:
+
+- `Laminas\Paginator\Adapter\Exception\RuntimeException`
+- `Laminas\Paginator\Adapter\Exception\UnexpectedValueException`
+- `Laminas\Paginator\Exception\UnexpectedValueException`
+
+### Laminas MVC Module Manager Support
+
+The `Module` class has been removed.
+It is possible to use the shipped `ConfigProvider` to ensure that the library is correctly configured for use with the application Service Manager.
+
+### 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](../configuration.md#the-paginator-factory-service).

docs/book/v3/migration/from-v2-to-v3.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.

docs/book/v3/usage.md

@@ -8,8 +8,11 @@ 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':
+            - 'From v2 to v3': v3/migration/from-v2-to-v3.md
     - v2:
         - Introduction: v2/intro.md
         - Installation: v2/installation.md

mkdocs.yml

@@ -8,6 +8,7 @@
     findUnusedCode="true"
     findUnusedBaselineEntry="true"
     findUnusedPsalmSuppress="true"
+    ensureOverrideAttribute="false"
 >
     <projectFiles>
         <directory name="src"/>
@@ -18,12 +19,6 @@
     </projectFiles>
 
     <issueHandlers>
-        <MissingOverrideAttribute>
-            <errorLevel type="suppress">
-                <directory name="src" />
-                <directory name="test" />
-            </errorLevel>
-        </MissingOverrideAttribute>
     </issueHandlers>
     <plugins>
         <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>