From eaeda36bdb934630dcde94eaee64e3065f14d0b5 Mon Sep 17 00:00:00 2001
From: Benjamin Eberlei <kontakt@beberlei.de>
Date: Tue, 31 Jul 2012 23:58:37 +0200
Subject: [PATCH] Add filtering collections

---
 en/reference/association-mapping.rst       |  1 +
 en/reference/working-with-associations.rst | 79 ++++++++++++++++++++++
 en/reference/working-with-objects.rst      | 10 +++
 3 files changed, 90 insertions(+)

diff --git a/en/reference/association-mapping.rst b/en/reference/association-mapping.rst
index 8c20693af..0b83b7474 100644
--- a/en/reference/association-mapping.rst
+++ b/en/reference/association-mapping.rst
@@ -1136,3 +1136,4 @@ been associated with an EntityManager yet:
     $group = $entityManager->find('Group', $groupId);
     $user = new User();
     $user->getGroups()->add($group);
+
diff --git a/en/reference/working-with-associations.rst b/en/reference/working-with-associations.rst
index caa9266ed..fee7d6731 100644
--- a/en/reference/working-with-associations.rst
+++ b/en/reference/working-with-associations.rst
@@ -608,3 +608,82 @@ you have also removed the references for standing data and as well as one
 address reference. When flush is called not only are the references removed 
 but both the old standing data and the one address entity are also deleted 
 from the database.
+
+Filtering Collections
+---------------------
+
+.. filtering-collections:
+
+Collections have a filtering API that allows to slice parts of data from
+a collection. If the collection has not been loaded from the database yet,
+the filtering API can work on the SQL level to make optimized access to
+large collections.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Collections\Criteria;
+
+    $group          = $entityManager->find('Group', $groupId);
+    $userCollection = $group->getUsers();
+    $expr           = $userCollection->getExpressionBuilder();
+
+    $criteria = Criteria::create();
+    $criteria->where($expr->eq("birthday", "1982-02-17"));
+
+    $birthdayUsers = $userCollection->matching($criteria);
+
+The Criteria has a limited matching language that works both on the
+SQL and on the PHP collection level. This means you can use collection matching
+interchangeably, independent of in-memory or sql-backed collections.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctrine\Common\Collections;
+
+    class Criteria
+    {
+        /**
+         * @return Criteria
+         */
+        static public function create();
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function where(Expression $where);
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function andWhere(Expression $where);
+        /**
+         * @param Expression $where
+         * @return Criteria
+         */
+        public function orWhere(Expression $where);
+        /**
+         * @param array $orderings
+         * @return Criteria
+         */
+        public function orderBy(array $orderings);
+        /**
+         * @param int $firstResult
+         * @return Criteria
+         */
+        public function setFirstResult($firstResult);
+        /**
+         * @param int $maxResults
+         * @return Criteria
+         */
+        public function setMaxResults($maxResults);
+        public function getOrderings();
+        public function getWhereExpresion();
+        public function getFirstResult();
+        public function getMaxResults();
+    }
+
+You can build expressions through the ExpressionBuilder
diff --git a/en/reference/working-with-objects.rst b/en/reference/working-with-objects.rst
index 531a14f50..e1ee8ebbe 100644
--- a/en/reference/working-with-objects.rst
+++ b/en/reference/working-with-objects.rst
@@ -728,6 +728,16 @@ examples are equivalent:
     // A single user by its nickname (__call magic)
     $user = $em->getRepository('MyProject\Domain\User')->findOneByNickname('romanb');
 
+By Criteria
+~~~~~~~~~~~
+
+The Repository implement the ``Doctrine\Common\Collections\Selectable``
+interface. That means you can build ``Doctrine\Common\Collections\Criteria``
+and pass them to the ``matching($criteria)`` method.
+
+See the :ref:`Working with Associations: Filtering collections
+<filtering-collections>`.
+
 By Eager Loading
 ~~~~~~~~~~~~~~~~