Add section on pagination for custom Data Prviders

Author: toby-griffiths

core/data-providers.md

@@ -243,3 +243,53 @@ final class BlogPostItemDataProvider implements ItemDataProviderInterface, Restr
 
 If you don't want to use the built-in Doctrine system, alternative approaches which offer an integration with API Platform exist.
 * [Pomm Data Provider](https://github.com/pomm-project/pomm-api-platform): ([Pomm](http://www.pomm-project.org/) is a database access framework dedicated to PostgreSQL database.
+
+
+## Pagination
+
+If you are implementing your own collection Data Provider, then you might also want to support pagination.  You can do
+this by returning a `\ApiPlatform\Core\DataProvider\PaginatorInterface` instance.  API Platform provides a few
+non-vendor specific paginators, e.g. `\ApiPlatform\Core\DataProvider\ArrayPaginator` and
+`\ApiPlatform\Core\DataProvider\TraversablePaginator`. See the [Pagination page](pagination.md) for more information on
+pagination.
+
+You can access the paging information by injecting the `\ApiPlatform\Core\DataProvider\Pagination` service, and then
+using it within your Data Provider…
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\DataProvider;
+
+use ApiPlatform\Core\DataProvider\CollectionDataProviderInterface;
+use ApiPlatform\Core\DataProvider\Pagination;
+use ApiPlatform\Core\DataProvider\PaginatorInterface;
+use ApiPlatform\Core\DataProvider\TraversablePaginator;
+use ArrayIterator;
+
+class CustomCollectionDataProvider implements CollectionDataProviderInterface
+{
+    private Pagination $pagination;
+
+
+    public function __construct(Pagination $pagination)
+    {
+        $this->pagination = $pagination;
+    }
+
+
+    public function getCollection(string $resourceClass, string $operationName = null, array $context = []): PaginatorInterface
+    {
+        $page = $this->pagination->getPage($context);
+        $itemsPerPage = $this->pagination->getLimit($resourceClass, $operationName, $context);
+
+        $data = [/* My results */];
+        $results = new ArrayIterator($data);
+        $totalItems = count($data);
+
+        return new TraversablePaginator($results, $page, $itemsPerPage, $totalItems);
+    }
+}
+```