Merge pull request #771 from teohhanhui/fix/doctrine-orm-paginator

Rewrite the section on Doctrine ORM Paginator

Author: dunglas

core/pagination.md

@@ -320,31 +320,67 @@ class Book
 }
 ```
 
-## Avoiding double SQL requests on Doctrine ORM
+## Controlling the behavior of the Doctrine ORM Paginator
 
-By default, the pagination assumes that there will be a collection fetched on a resource and thus will set `useFetchJoinCollection` to `true` on the Doctrine Paginator class. Having this option implies that 2 SQL requests will be executed (to avoid having less results than expected).
+The [PaginationExtension](https://github.com/api-platform/core/blob/master/src/Bridge/Doctrine/Orm/Extension/PaginationExtension.php) of API Platform performs some checks on the `QueryBuilder` to guess, in most common cases, the correct values to use when configuring the Doctrine ORM Paginator:
 
-In most cases, even without collection on the resource, this parameter has little impact on performance. However when fetching a lot of results per page it can be counter productive.
+-   `$fetchJoinCollection` argument: Whether there is a join to a collection-valued association. When set to `true`, the Doctrine ORM Paginator will perform an additional query, in order to get the correct number of results.
 
-That's why this behavior can be configured with the `pagination_fetch_join_collection` parameter on a resource:
+    You can configure this using the `pagination_fetch_join_collection` attribute on a resource or on a per-operation basis:
 
-```php
-<?php
-
-// api/src/Entity/Book.php
+    ```php
+    <?php
+    // api/src/Entity/Book.php
 
-use ApiPlatform\Core\Annotation\ApiResource;
+    use ApiPlatform\Core\Annotation\ApiResource;
 
-/**
- * @ApiResource(attributes={"pagination_fetch_join_collection"=false})
- */
-class Book
-{
-    // ...
-}
-```
+    /**
+    * @ApiResource(
+    *     attributes={"pagination_fetch_join_collection"=false},
+    *     collectionOperations={
+    *         "get",
+    *         "get_custom"={
+    *             ...
+    *             "pagination_fetch_join_collection"=true,
+    *         },
+    *     },
+    * )
+    */
+    class Book
+    {
+        // ...
+    }
+    ```
+
+-   `setUseOutputWalkers` setter: Whether to use output walkers. When set to `true`, the Doctrine ORM Paginator will use output walkers, which are compulsory for some types of queries.
+
+    You can configure this using the `pagination_use_output_walkers` attribute on a resource or on a per-operation basis:
+
+    ```php
+    <?php
+    // api/src/Entity/Book.php
+
+    use ApiPlatform\Core\Annotation\ApiResource;
+
+    /**
+    * @ApiResource(
+    *     attributes={"pagination_use_output_walkers"=false},
+    *     collectionOperations={
+    *         "get",
+    *         "get_custom"={
+    *             ...
+    *             "pagination_use_output_walkers"=true,
+    *         },
+    *     },
+    * )
+    */
+    class Book
+    {
+        // ...
+    }
+    ```
 
-Please note that this parameter will always be forced to false when the resource has composite keys due to a [bug in Doctrine](https://github.com/doctrine/orm/issues/2910).
+For more information, please see the [Pagination](https://www.doctrine-project.org/projects/doctrine-orm/en/current/tutorials/pagination.html) entry in the Doctrine ORM documentation.
 
 ## Custom Controller Action