Merge pull request #188 from zf-fr/best-practices

Start writing best practices

Author: bakura10

docs/04. Using HTTP exceptions for reporting errors.md

@@ -75,5 +75,6 @@ return [
 
 ### Navigation
 
-* Back to [the Introduction](/docs/03. View layer.md)
+* Continue to [**Best practices**](/docs/05. Best practices.md)
+* Back to [the View Layer](/docs/03. View layer.md)
 * Back to [the Index](/docs/README.md)

docs/05. Best practices.md

@@ -0,0 +1,342 @@
+# Best Practices
+
+This section will show you various best practices that I've learn while writing several REST API, using ZfrRest.
+
+## Be pragmatic
+
+I know a lot of people will disagree with that, but you should be pragmatic when using your API. HATEOAS is nice,
+but it's actually not really needed (whenever I use an API, I never ever used the URL attributes of such APIs,
+because the workflow of which method to call is usually known in advance).
+
+If being 100% REST compliant takes too much time or is not useful for your use case, don't lose time on that and
+go on.
+
+[This link](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api) contains a lot of best practices
+when designing an API.
+
+## Use nested URIs
+
+ZfrRest allows you to nest URLs, for accessing the same resource based on different contexts. For instance, if you
+have tweets, you can either access all tweets (`/tweets`) but also access all tweets from a given user (`/users/1/tweets`).
+
+With the template feature of ZfrRest, you do not have to write rendering code multiple times. Instead, you will use
+the exact same template for the two cases, except with different set of data.
+
+## List and resource controllers
+
+You have to understand that you will typically have two controllers per resource: the list controller and the
+item controller. You should have a coherent naming that you use throughout your application (for instance you
+could add the `List` word for list controllers: `TweetController` and `TweetListController`).
+
+This table will recap you the type of controller based on URI and verb:
+
+URI | Verb | Type
+------------ | ------------- | ------------
+/tweets | POST  | List controller
+/tweets | GET  | List controller
+/tweets | PUT  | N/A
+/tweets | DELETE  | N/A
+/tweets/1 | POST | N/A
+/tweets/1 | GET | Item controller
+/tweets/1 | PUT | Item controller
+/tweets/1 | DELETE | Item controller
+
+## Simplify your controllers
+
+Controllers are known to be hard to test (you have to mock requests...). Instead, all your controllers must be kept
+very simple. To do that, you should use a service layer. In ZfrRest, here is how your controller typically look like.
+
+* List controller
+
+```php
+class TweetListController extends AbstractRestfulController
+{
+    private $tweetService;
+
+    public function __construct(TweetService $tweetService)
+    {
+        $this->tweetService = $tweetService;
+    }
+
+    /**
+     * Create a new tweet
+     */
+    public function post()
+    {
+        $data  = $this->validateIncomingData(TweetInputFilter::class);
+        $tweet = $this->hydrateObject(TweetHydrator::class, new Tweet(), $data);
+
+        $tweet = $this->tweetService->create($tweet);
+
+        return new ResourceViewModel(['tweet' => $tweet], ['template' => 'tweets/tweet']);
+    }
+
+    /**
+     * Get all the tweets
+     */
+    public function get()
+    {
+        // Assuming getAll return a paginator
+        $tweets = $this->tweetService->getAll();
+        $tweets->setCurrentPageNumber($this->params()->fromQuery('page', 1);
+
+        return new ResourceViewModel(['tweets' => $tweets], ['template' => 'tweets']);
+    }
+}
+```
+
+* Item controller
+
+```php
+class TweetController extends AbstractRestfulController
+{
+    private $tweetService;
+
+    public function __construct(TweetService $tweetService)
+    {
+        $this->tweetService = $tweetService;
+    }
+
+    /**
+     * Get an existing tweet
+     */
+    public function get(array $params)
+    {
+        if (!$tweet = $this->tweetService->getById($params['tweet_id'])) {
+            throw new NotFoundException();
+        }
+
+        return new ResourceViewModel(['tweet' => $tweet], ['template' => 'tweets/tweet']);
+    }
+
+    /**
+     * Update an existing tweet
+     */
+    public function put(array $params)
+    {
+        if (!$tweet = $this->tweetService->getById($params['tweet_id'])) {
+            throw new NotFoundException();
+        }
+
+        $data  = $this->validateIncomingData(TweetInputFilter::class);
+        $tweet = $this->hydrateObject(TweetHydrator::class, $tweet, $data);
+
+        $tweet = $this->tweetService->update($tweet);
+
+        return new ResourceViewModel(['tweet' => $tweet], ['template' => 'tweets/tweet']);
+    }
+
+    /**
+     * Delete an existing tweet
+     */
+    public function delete(array $params)
+    {
+        if (!$tweet = $this->tweetService->getById($params['tweet_id'])) {
+            throw new NotFoundException();
+        }
+
+        $this->tweetService->delete($tweet);
+
+        return new JsonModel();
+    }
+}
+```
+
+## Paginate data
+
+To paginate data, you need to create an instance of `Zend\Paginator\Paginator`. DoctrineModule and DoctrineORMModule
+offers two adapters for Doctrine, that you can use depending on the use case: `DoctrineModule\Paginator\Adapter\Selectable`
+and `DoctrineORMModule\Paginator\Adapter\DoctrinePaginator`.
+
+We recommend you to create the paginator in your repositories (or your services). Two cases can happen:
+
+1. If you do not need a custom query (for instance if you only want to fetch the tweets, without any join or whatever),
+you can use the `Selectable` adapter, because repositories implement the `Selectable` interface. For instance, in your
+service:
+
+```php
+use DoctrineModule\Paginator\Adapter\Selectable as SelectableAdapter;
+use Zend\Paginator\Paginator;
+
+class TweetService
+{
+    private $tweetRepository;
+
+    public function getAll()
+    {
+        return new Paginator(new SelectableAdapter($this->tweetRepository));
+    }
+}
+```
+
+> You can optionally pass a criteria object for filtering, as we'll see later.
+
+2. If you need custom query, this approach is not flexible enough. We recommend you in this case to create a
+custom repository, that will create the query, and wrap it under a paginator:
+
+First, your service now delegate to the repository:
+
+```php
+class TweetService
+{
+    private $tweetRepository;
+
+    public function getAll()
+    {
+        return new $this->tweetRepository->findAll();
+    }
+}
+```
+
+While your TweetRepository create the custom query, and wrap it around a Paginator:
+
+```php
+use Doctrine\ORM\Tools\Pagination\Paginator as DoctrinePaginator;
+use DoctrineORMModule\Paginator\Adapter\DoctrinePaginator as DoctrinePaginatorAdapter;
+use Zend\Paginator\Paginator;
+
+class TweetRepository extends EntityRepository
+{
+    public function findAll()
+    {
+        $queryBuilder = $this->createQueryBuilder('tweet');
+        $queryBuilder->select('author')
+                     ->join('tweet.author', 'author');
+
+        $doctrinePaginator = new DoctrinePaginator($queryBuilder);
+        return new Paginator(new DoctrinePaginatorAdapter($doctrinePaginator));
+    }
+}
+```
+
+## Filtering data
+
+When retrieving data, you will often need to filter the result set through query parameters. One approach to do
+that is to extract the query params right into your controllers, and passing each filters to your service, which
+in turn will do the right query.
+
+However, we definitely do not want to tie your controller to query params parsing. Once again, two cases can happen:
+
+* You have simple filtering needs, when you only need to filter the fields of the entity you are fetching (for instance,
+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)

docs/README.md

@@ -20,4 +20,6 @@ If you are looking for some information that is not listed in the documentation,
 
 4. [Using HTTP exceptions for reporting errors](/docs/04. Using HTTP exceptions for reporting errors.md)
     1. [Built-in exceptions](/docs/04. Using HTTP exceptions for reporting errors.md#built-in-exceptions)
-    2. [Mapping custom exceptions](/docs/04. Using HTTP exceptions for reporting errors.md#mapping-custom-exceptions)
+    2. [Mapping custom exceptions](/docs/04. Using HTTP exceptions for reporting errors.md#mapping-custom-exceptions)
+
+5. [Best Practices](/docs/05. Best practices.md)