Merge pull request #89 from gsteel/v3/docs

Update documentation for v3

Author: gsteel

docs/book/v3/advanced.md

@@ -4,7 +4,7 @@
 
 laminas-paginator ships with a plugin manager for adapters, `Laminas\Paginator\AdapterPluginManager`.
 The plugin manager can be used to retrieve adapters.
-Since most adapters require constructor arguments, they may be passed as the second argument to the `get()` method in the same order they appear in the constructor.
+Since most adapters require constructor arguments, they may be passed as the second argument to the `build()` method in the same order they appear in the constructor.
 
 ### Examples
 
@@ -15,42 +15,37 @@ use Laminas\Paginator\AdapterPluginManager;
 $pluginManager = new AdapterPluginManager();
 
 // Get an array adapter for an array of items
-$arrayAdapter = $pluginManager->get(Adapter\ArrayAdapter::class, [$arrayOfItems]);
+$arrayAdapter = $pluginManager->build(Adapter\ArrayAdapter::class, [$arrayOfItems]);
 
 // Get an Iterator adapter based on an iterator:
-$iteratorAdapter = $pluginManager->get(Adapter\Iterator::class, [$iterator]);
+$iteratorAdapter = $pluginManager->build(Adapter\Iterator::class, [$iterator]);
 ```
 
 ## Custom data source adapters
 
-At some point you may run across a data type that is not covered by the packaged
-adapters. In this case, you will need to write your own.
+At some point you may run across a data type that is not covered by the packaged adapters.
+In this case, you will need to write your own.
 
-To do so, you must implement `Laminas\Paginator\Adapter\AdapterInterface`. There
-are two methods required to do this:
+To do so, you must implement `Laminas\Paginator\Adapter\AdapterInterface`.
+There are two methods required to do this:
 
-- `count() : int`
-- `getItems(int $offset, int $itemCountPerPage) | array`
+- `count(): int`
+- `getItems(int $offset, int $itemCountPerPage): iterable`
 
-Additionally, you'll typically implement a constructor that takes your data
-source as a parameter.
+Additionally, you'll typically implement a constructor that takes your data source as a parameter.
 
-If you've ever used the SPL interface [Countable](http://php.net/Countable),
-you're familiar with `count()`. As used with laminas-paginator, this is the total
-number of items in the data collection; `Laminas\Paginator\Paginator::countAllItems`
-proxies to this method.
+If you've ever used the SPL interface [Countable](http://php.net/Countable), you're familiar with `count()`.
+As used with `laminas-paginator`, this is the total number of items in the data collection; `Laminas\Paginator\Paginator::countAllItems` proxies to this method.
 
-When retrieving items for the current page, `Laminas\Paginator\Paginator` calls on
-your adapter's `getItems()` method, providing it with an offset and the number
-of items to display per page; your job is to return the appropriate slice of
-data. For an array, that would be:
+When retrieving items for the current page, `Laminas\Paginator\Paginator` calls on your adapter's `getItems()` method, providing it with an offset and the number of items to display per page;
+your job is to return the appropriate slice of data.
+For an array, that would be:
 
 ```php
 return array_slice($this->array, $offset, $itemCountPerPage);
 ```
 
-Take a look at the packaged adapters for ideas of how you might go about
-implementing your own.
+Take a look at the packaged adapters for ideas of how you might go about implementing your own.
 
 ### Registering Your Adapter with the Plugin Manager
 
@@ -85,47 +80,8 @@ class SomeServiceFactory
     public function __invoke(ContainerInterface $container)
     {
         $paginators = $container->get(AdapterPluginManager::class);
-        $paginator  = new Paginator($paginators->get(YourCustomPaginatorAdapter::class));
+        $paginator  = new Paginator($paginators->build(YourCustomPaginatorAdapter::class, $someOptions));
         // ...
     }
 }
 ```
-
-## Custom scrolling styles
-
-Creating your own scrolling style requires that you implement
-`Laminas\Paginator\ScrollingStyle\ScrollingStyleInterface`, which defines a single
-method:
-
-```php
-getPages(Paginator $paginator, int $pageRange = null) : array
-```
-
-This method should calculate a lower and upper bound for page numbers within the
-range of so-called "local" pages (that is, pages that are nearby the current
-page).
-
-Unless it extends another scrolling style (see
-`Laminas\Paginator\ScrollingStyle\Elastic` for an example), your custom scrolling
-style will inevitably end with something similar to the following line of code:
-
-```php
-return $paginator->getPagesInRange($lowerBound, $upperBound);
-```
-
-There's nothing special about this call; it's merely a convenience method to
-check the validity of the lower and upper bound and return an array with the range
-to the paginator.
-
-When you're ready to use your new scrolling style, you'll need to notif
-`Laminas\Paginator\Paginator`:
-
-```php
-use My\Paginator\ScrollingStyle;
-use Laminas\Paginator\Paginator;
-use Laminas\ServiceManager\Factory\InvokableFactory;
-
-$manager = Paginator::getScrollingStyleManager();
-$manager->setAlias('my-style', ScrollingStyle::class);
-$manager->setFactory(ScrollingStyle::class, InvokableFactory::class);
-```

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

@@ -1,16 +1,13 @@
 # Stand-Alone
 
-The paginator can also be used stand-alone, outside of a Mezzio or laminas-mvc
-application.
+The paginator can be used stand-alone, outside a Mezzio or laminas-mvc application.
 
 The example uses the following directory structure:
 
 ```treeview
 example-app/
 |-- public/
 |   `-- index.php
-|-- templates/
-|   `-- pagination-control.phtml
 `-- vendor
     `-- …
 ```

docs/book/v3/configuration.md

@@ -1,9 +1,60 @@
 # Configuration
 
-`Laminas\Paginator` has several configuration methods that can be called:
+`Laminas\Paginator` is designed to work with `laminas-servicemanager` as its dependency injection container.
 
-Method signature                                             | Description
------------------------------------------------------------- | -----------
-`setCurrentPageNumber(int $page) : void`                     | Sets the current page number (default 1).
-`setItemCountPerPage(int $count) : void`                     | Sets the maximum number of items to display on a page (default 10).
-`setPageRange(int $range) : void`                            | Sets the number of items to display in the pagination control (default 10). Note: Most of the time this number will be adhered to exactly, but scrolling styles do have the option of only using it as a guideline or starting value (e.g., Elastic).
+It is perfectly possible to use Paginator without using Laminas Service Manager as the DIC in your project, but some convenience will be sacrificed.
+
+## Configuring Pagination Defaults
+
+The following configuration would be returned as part of the `config` service returned from the DI container, so it would be inserted into a PHP file that is autoloaded during bootstrap, or in a `ConfigProvider` perhaps:
+
+```php
+return [
+    'paginator' => [
+        'itemCountPerPage' => 10,
+        'pageRange'        => 10,
+        'scrollingStyle'   => 'Sliding',
+    ],
+];
+```
+
+The above configures the default page size to 10, the default page range to 10 and uses the `Sliding` scrolling style by default.
+
+## The Paginator Factory Service
+
+In order for these defaults to apply to newly created paginators, you must use the `PaginatorFactory` service to delegate construction of your paginators:
+
+### Create a Paginator by Providing a Concrete Adapter
+
+```php
+use Laminas\Paginator\Adapter\ArrayAdapter;
+use Laminas\Paginator\PaginatorFactory;
+
+$factory = $container->get(PaginatorFactory::class);
+$paginator = $factory->withAdapter(new ArrayAdapter([1, 2, 3]));
+// The paginator above will now be configured with the defaults you have specified.
+```
+
+By using the `PaginatorFactory`, you can ensure consistent configuration of paginators across your application with a single place where these defaults can be changed, instead of hard-coding preferences into every call to `new Paginator(...)`.
+
+The factory has 2 more methods for building paginators:
+
+### Create a Paginator by Providing Configuration for an Adapter
+
+```php
+use Laminas\Paginator\Adapter\ArrayAdapter;
+use Laminas\Paginator\PaginatorFactory;
+
+$factory = $container->get(PaginatorFactory::class);
+$paginator = $factory->buildAdapter(ArrayAdapter::class, ['some', 'items', 'to', 'paginate']);
+```
+
+### Create a Paginator with an Iterable
+
+```php
+use Laminas\Paginator\Adapter\ArrayAdapter;
+use Laminas\Paginator\PaginatorFactory;
+
+$factory = $container->get(PaginatorFactory::class);
+$paginator = $factory->withItems(['some', 'items', 'to', 'paginate']);
+```

docs/book/v3/images/usage-rendering-control.png

@@ -7,7 +7,5 @@ The primary design goals of laminas-paginator are as follows:
 
 - Paginate arbitrary data, not just relational databases.
 - Fetch only the results that need to be displayed.
-- Do not force users to adhere to only one way of displaying data or rendering
-  pagination controls.
-- Loosely couple to other Laminas components so that users who wish to
-  use it independently of laminas-view, laminas-cache, etc. can do so.
+- Do not force users to adhere to only one way of displaying data or rendering pagination controls.
+- Remain uncoupled from framework dependencies