Add filters

Author: bakura10

docs/05. Best practices.md

@@ -177,9 +177,6 @@ custom repository, that will create the query, and wrap it under a paginator:
 First, your service now delegate to the repository:
 
 ```php
-use DoctrineModule\Paginator\Adapter\Selectable as SelectableAdapter;
-use Zend\Paginator\Paginator;
-
 class TweetService
 {
     private $tweetRepository;
@@ -225,6 +222,121 @@ filtering by first name, last name or age when retrieving a list of users).
 * You have more complex filtering needs, when you can possibly also filter by properties of associations (for instance,
 you want to filter by author first name when retrieving a list of tweets).
 
+### Simple filtering
+
+For filtering fields on the same entity, you can use a Criteria object. The Criteria object is a Doctrine abstraction
+that allows to filtering collections (it also works on repository) efficiently. For instance, let's say you want
+to filter users by first name and last name. To do that, you allow `first_name` and `last_name` query params:
+
+```php
+use Doctrine\Common\Collections\Criteria;
+
+class UserListController extends AbstractRestfulController
+{
+    private $userService;
+
+    public function get()
+    {
+        // Get all the query params
+        $queryParams = $this->params()->fromQuery();
+
+        // Create the criteria object
+        $criteria = new Criteria();
+        $builder  = $criteria->expr();
+
+        foreach ($queryParams as $key => $value) {
+            switch ($key) {
+                case 'first_name':
+                    $criteria->andWhere($builder->eq('firstName', $value));
+                    break;
+
+                case 'last_name':
+                    $criteria->andWhere($builder->eq('lastName', $value));
+                    break;
+            }
+        }
+
+        $users = $this->userService->getAllByCriteria($criteria);
+
+        return new ResourceViewModel(['users' => $users]);
+    }
+}
+```
+
+With your `getAllByCriteria` creating a paginator, but with the Criteria object to further filtering the data set:
+
+```php
+use DoctrineModule\Paginator\Adapter\Selectable as SelectableAdapter;
+use Zend\Paginator\Paginator;
+
+class UserService
+{
+    private $userRepository;
+
+    public function getAllByCriteria(Criteria $criteria)
+    {
+        return new Paginator(new SelectableAdapter($this->tweetRepository, $criteria));
+    }
+}
+```
+
+> As you can see, we can easily combine filtering and pagination thanks to the power of the Criteria API!
+
+However, there is a problem with this approach: our controller is now polluted with code that is difficult to
+test in isolation, and cannot be reused elsewhere. To solve this problem, we introduce a new kind of objects: the
+Criteria objects.
+
+Those objects simply extend the base Criteria, but know how to build the criteria object. For instance, here is
+a UserCriteria object:
+
+```php
+class UserCriteria extends Criteria
+{
+    public function __construct(array $filters = [])
+    {
+        $builder = $this->expr();
+
+        foreach ($queryParams as $key => $value) {
+            switch ($key) {
+                case 'first_name':
+                    $this->andWhere($builder->eq('firstName', $value));
+                    break;
+
+                case 'last_name':
+                    $this->andWhere($builder->eq('lastName', $value));
+                    break;
+            }
+        }
+    }
+}
+```
+
+Your controller now become:
+
+```php
+use Doctrine\Common\Collections\Criteria;
+
+class UserListController extends AbstractRestfulController
+{
+    private $userService;
+
+    public function get()
+    {
+        $criteria = new UserCriteria($this->params()->fromQuery(null, []));
+        $users    = $this->userService->getAllByCriteria($criteria);
+
+        return new ResourceViewModel(['users' => $users]);
+    }
+}
+```
+
+Much cleaner!
+
+### Complex filtering
+
+This works well when filtering on fields that belong to the entity. However, the Criteria API is a rather limited API,
+and does not allow things such as filtering on association using joins. We therefore need to resolve to a similar
+approach, but without using the Criteria API itself.
 
 * Back to [**Using HTTP exceptions for reporting errors**](/docs/04. Using HTTP exceptions for reporting errors.md)
 * Back to [the Index](/docs/README.md)