Merge pull request #154 from dunglas/paginator_extension_point

Extension point for Paginator. Disable output walkers by default.

Author: dunglas

Doctrine/Orm/DataProvider.php

@@ -13,6 +13,7 @@
 
 use Doctrine\Common\Persistence\ManagerRegistry;
 use Doctrine\ORM\Tools\Pagination\Paginator as DoctrineOrmPaginator;
+use Doctrine\ORM\QueryBuilder;
 use Dunglas\ApiBundle\Doctrine\Orm\Filter\FilterInterface;
 use Dunglas\ApiBundle\Model\DataProviderInterface;
 use Dunglas\ApiBundle\Api\ResourceInterface;
@@ -126,7 +127,23 @@ public function getCollection(ResourceInterface $resource, Request $request)
             $queryBuilder->addOrderBy('o.'.$identifier, $this->order);
         }
 
-        return new Paginator(new DoctrineOrmPaginator($queryBuilder));
+        return $this->getPaginator($queryBuilder);
+    }
+
+    /**
+     * Gets the paginator.
+     *
+     * @param QueryBuilder $queryBuilder
+     *
+     * @return Paginator
+     */
+    protected function getPaginator(QueryBuilder $queryBuilder)
+    {
+        $doctrineOrmPaginator = new DoctrineOrmPaginator($queryBuilder);
+        // Disable output walkers by default (performance)
+        $doctrineOrmPaginator->setUseOutputWalkers(false);
+
+        return new Paginator($doctrineOrmPaginator);
     }
 
     /**

README.md

@@ -55,7 +55,8 @@ This bundle is documented and tested with Behat (take a look at [the `features/`
 4. [Data providers](Resources/doc/data-providers.md)
   1. [Creating a custom data provider](Resources/doc/data-providers.md#creating-a-custom-data-provider)
   2. [Returning a paged collection](Resources/doc/data-providers.md#returning-a-paged-collection)
-  3. [Supporting filters](Resources/doc/data-providers.md#Supporting-filters)
+  3. [Supporting filters](Resources/doc/data-providers.md#supporting-filters)
+  4. [Extending the Doctrine Data Provider](Resources/doc/data-providers.md#extending-the-doctrine-data-provider)
 5. [Filters](Resources/doc/filters.md)
   1. [Search filter](Resources/doc/filters.md#search-filter)
   2. [Date filter](Resources/doc/filters.md#date-filter)

Resources/config/doctrine_orm.xml

@@ -16,14 +16,16 @@
             <tag name="kernel.event_subscriber" />
         </service>
 
-        <service id="api.doctrine.orm.data_provider" class="Dunglas\ApiBundle\Doctrine\Orm\DataProvider" public="false">
+        <service id="api.doctrine.orm.data_provider" public="false" abstract="true">
             <argument type="service" id="doctrine" />
             <argument>%api.collection.order%</argument>
             <argument>%api.collection.pagination.page_parameter_name%</argument>
             <argument>%api.collection.pagination.items_per_page.number%</argument>
             <argument>%api.collection.pagination.items_per_page.enable_client_request%</argument>
             <argument>%api.collection.pagination.items_per_page.parameter_name%</argument>
+        </service>
 
+        <service id="api.doctrine.orm.default_data_provider" parent="api.doctrine.orm.data_provider" class="Dunglas\ApiBundle\Doctrine\Orm\DataProvider">
             <tag name="api.data_provider" />
         </service>
 

Resources/doc/data-providers.md

@@ -1,7 +1,7 @@
 # Data providers
 
 To retrieve data that will be exposed by the API, DunglasApiBundle use classes called data providers. A data provider
-using Doctrine ORM to retrieve data from a database is included with the bundle and enabled by default. This data provider
+using [Doctrine ORM](http://www.doctrine-project.org/projects/orm.html) to retrieve data from a database is included with the bundle and enabled by default. This data provider
 natively supports paged collection and filters. It can be used as is and fits perfectly with common usages.
 
 But sometime, you want to retrieve data from other sources such as a webservice, ElasticSearch, MongoDB or another ORM.
@@ -85,5 +85,56 @@ To create your own paginators, take a look at the Doctrine ORM paginator bridge:
 To be able [to filter collections](filters.md), the Data Provider must be aware of registered filters to the given resource.
 The best way to learn how to create filter aware data provider is too look at the default Doctrine ORM dataprovider: [`Dunglas\ApiBundle\Doctrine\Orm\DataProvider`](/Doctrine/Orm/DataProvider.php).
 
+## Extending the Doctrine Data Provider
+
+The bundle is provided with a data provider leveraging the Doctrine ORM. This default data provider can be extended.
+
+For performance reasons, [custom output walkers for the Doctrine ORM Paginator](http://www.doctrine-project.org/jira/browse/DDC-3282)
+are disabled. It drastically improves performance when dealing with large collections. However it prevents advanced [filters](filters.md)
+adding `HAVING` and `GROUP BY` clauses to DQL queries to work properly.
+
+To enable custom output walkers, start by creating a custom data provider supporting the `AppBundle\Entity\MyEntity` class:
+
+```php
+<?php
+
+// src/AppBundle/DataProvider/MyEntityDataProvider.php
+
+namespace AppBundle\DataProvider;
+
+use Dunglas\ApiBundle\Doctrine\Orm\DataProvider;
+use Dunglas\ApiBundle\Model\DataProviderInterface;
+
+class MyEntityDataProvider extends DataProvider
+{
+    protected function getPaginator(QueryBuilder $queryBuilder)
+    {
+        $doctrineOrmPaginator = new DoctrineOrmPaginator($queryBuilder);
+        // Enable output walkers to make queries with HAVING and ORDER BY clauses working
+        $doctrineOrmPaginator->setUseOutputWalkers(true);
+
+        return new Paginator($doctrineOrmPaginator);
+    }
+    
+    public function supports(ResourceInterface $resource)
+    {
+        return 'AppBundle\Entity\MyEntity' === $resource->getEntityClass();
+    }
+}
+```
+
+Then register the data provider:
+
+```yaml
+
+# app/config/services.yml
+
+services:
+    my_entity_data_provider:
+        parent: "api.doctrine.orm.data_provider"
+        class: AppBundle\DataProvider\MyEntityDataProvider
+        tags:  [ { name: "api.data_provider", priority: 1 } ]
+```
+
 Previous chapter: [Operations](operations.md)<br>
 Next chapter: [Filters](filters.md)