feature #6502 Added the json() shortcut to the controller chapter (dfridrich, javiereguiluz)

This PR was submitted for the master branch but it was merged into the 3.1 branch instead (closes #6502).

Discussion
----------

Added the json() shortcut to the controller chapter

This is an alternative to #6453.

Commits
-------

8aa429d Syntax issue
f1441b2 Explained how contents are serialized
6824706 Fixed typo
95d5f2e Fixed minor typo
0316363 Fixes
78aa9cb Simplified everything
7a8ad76 Moved the json() helper explanation
97a2f9c Added the json() shortcut to the controller chapter
ba6a922 Update docs for JSON helper
91b2d00 Added docs for JSON helper

Author: wouterj

book/controller.rst

@@ -758,9 +758,9 @@ headers and content that's sent back to the client::
     // create a simple Response with a 200 status code (the default)
     $response = new Response('Hello '.$name, Response::HTTP_OK);
 
-    // create a JSON-response with a 200 status code
-    $response = new Response(json_encode(array('name' => $name)));
-    $response->headers->set('Content-Type', 'application/json');
+    // create a CSS-response with a 200 status code
+    $response = new Response('<style> ... </style>');
+    $response->headers->set('Content-Type', 'text/css');
 
 There are also special classes to make certain kinds of responses easier:
 
@@ -774,6 +774,27 @@ There are also special classes to make certain kinds of responses easier:
   :class:`Symfony\\Component\\HttpFoundation\\StreamedResponse`.
   See :ref:`streaming-response`.
 
+JSON Helper
+~~~~~~~~~~~
+
+Returning JSON contents is increasingly popular for API-based applications. For
+that reason, the base controller class defines a ``json()`` method which creates
+a ``JsonResponse`` and encodes the given contents automatically::
+
+    // ...
+    public function indexAction()
+    {
+        // returns '{"username":"jane.doe"}' and sets the proper Content-Type header
+        return $this->json(array('username' => 'jane.doe'));
+
+        // the shortcut defines three optional arguments
+        // return $this->json($data, $status = 200, $headers = array(), $context = array());
+    }
+
+If the :doc:`serializer service </cookbook/serializer>` is enabled in your
+application, contents passed to ``json()`` are encoded with it. Otherwise,
+the :phpfunction:`json_encode()` function is used.
+
 .. seealso::
 
     Now that you know the basics you can continue your research on Symfony