Add tutorial about Pagination

en/index.rst

@@ -25,7 +25,7 @@ of contents <toc>`.
 Getting Started
 ---------------
 
-* **Tutorial**: 
+* **Tutorial**:
   :doc:`Getting Started <tutorials/getting-started>` |
   :doc:`In 10 quick steps <tutorials/in-ten-quick-steps>`
 
@@ -59,20 +59,21 @@ Working with Objects
   :doc:`Assocations <reference/working-with-associations>` |
   :doc:`Events <reference/events>`
 
-* **Querying Objects**:
+* **Query Reference**:
   :doc:`Doctrine Query Language (DQL) <reference/dql-doctrine-query-language>` |
   :doc:`QueryBuilder <reference/query-builder>` |
   :doc:`Native SQL Queries <reference/native-sql>`
 
 * **UnitOfWork dissected**:
   :doc:`Doctrine Internals explained <reference/unitofwork>` |
-  :doc:`Owning and Inverse Side Associations <reference/unitofwork-associations>` 
+  :doc:`Owning and Inverse Side Associations <reference/unitofwork-associations>`
 
 * **Tutorials**:
   :doc:`Indexed associations <tutorials/working-with-indexed-associations>` |
   :doc:`Extra Lazy Assocations <tutorials/extra-lazy-associations>` |
   :doc:`Composite Primary Keys <tutorials/composite-primary-keys>` |
-  :doc:`Ordered associations <tutorials/ordered-associations>`
+  :doc:`Ordered associations <tutorials/ordered-associations>` |
+  :doc:`Pagination <tutorials/pagination>`
 
 Advanced Topics
 ---------------

en/tutorials/pagination.rst

@@ -0,0 +1,40 @@
+Pagination
+==========
+
+Starting with version 2.2 Doctrine ships with a Paginator for DQL queries. It
+has a very simple API and implements the SPL interfaces ``Countable`` and
+``IteratorAggregate``.
+
+Paginating Doctrine queries is not as simple as you might think in the
+beginning. If you have complex fetch-join scenarios with one-to-many or
+many-to-many associations using the "default" LIMIT functionality of database
+vendors is not sufficient to get the correct results.
+
+By default the pagination extension does the following steps to compute the
+correct result:
+
+1. Perform a Count query using `DISTINCT` keyword.
+2. Perform a Limit Subquery with `DISTINCT` to find all ids of the entity in from on the current page.
+3. Perform a WHERE IN query to get all results for the current page.
+
+This behavior is only necessary if you actually fetch join a to-many
+collection. You can disable this behavior by setting the
+``$fetchJoinCollection`` flag of. We hope to automate the detection for this in
+the future.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\Pagination\Paginator;
+
+    $dql = "SELECT p, c FROM BlogPost p JOIN p.comments c";
+    $query = $entityManager->createQuery($dql)
+                           ->setFirstResult(0)
+                           ->setMaxResults(100);
+
+    $paginator = new Paginator($query, $fetchJoin = true);
+
+    $c = count($paginator);
+    foreach ($paginator as $post) {
+        echo $post->getHeadline() . "\n";
+    }