minor #6062 Update HTTP method requirement example (WouterJ)

This PR was merged into the 2.3 branch.

Discussion
----------

Update HTTP method requirement example

| Q | A
| --- | ---
| Doc fix? | yes
| New docs? | no
| Applies to | 2.3+
| Fixed tickets | #5583

After many reports (#5779, #5659) of the text no longer matching the example, I think it's time to update the example.

The example now uses an API, which is a very common thing now and often needs this feature. API's are already used in the Page Creation article, which is placed before this article, so it shouldn't be too hard to understand.

I know that from a REST prespective, HEAD and GET using the same action doesn't seem that great, but it's the only action I could think of that may support 2 methods.

Commits
-------

30c2750 Update method requirement example

Author: xabbuh

book/routing.rst

@@ -815,10 +815,10 @@ Adding HTTP Method Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In addition to the URL, you can also match on the *method* of the incoming
-request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you have a contact form
-with two controllers - one for displaying the form (on a GET request) and one
-for processing the form when it's submitted (on a POST request). This can
-be accomplished with the following route configuration:
+request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you create an API for
+your blog and you have 2 routes: One for displaying a post (on a GET or HEAD
+request) and one for updating a post (on a PUT request). This can be
+accomplished with the following route configuration:
 
 .. configuration-block::
 
@@ -830,39 +830,39 @@ be accomplished with the following route configuration:
         use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
         // ...
 
-        class MainController extends Controller
+        class BlogApiController extends Controller
         {
             /**
-             * @Route("/news")
-             * @Method("GET")
+             * @Route("/api/posts/{id}")
+             * @Method({"GET","HEAD"})
              */
-            public function newsAction()
+            public function showAction($id)
             {
-                // ... display your news
+                // ... return a JSON response with the post
             }
 
             /**
-             * @Route("/contact")
-             * @Method({"GET", "POST"})
+             * @Route("/api/posts/{id}")
+             * @Method("PUT")
              */
-            public function contactFormAction()
+            public function editAction($id)
             {
-                // ... display and process a contact form
+                // ... edit a post
             }
         }
 
     .. code-block:: yaml
 
         # app/config/routing.yml
-        news:
-            path:     /news
-            defaults: { _controller: AppBundle:Main:news }
-            methods:  [GET]
+        api_show_post:
+            path:     /api/posts/{id}
+            defaults: { _controller: AppBundle:BlogApi:show }
+            methods:  [GET, HEAD]
 
-        contact_form:
-            path:     /contact
-            defaults: { _controller: AppBundle:Main:contactForm }
-            methods:  [GET, POST]
+        api_edit_post:
+            path:     /api/posts/{id}
+            defaults: { _controller: AppBundle:BlogApi:edit }
+            methods:  [PUT]
 
     .. code-block:: xml
 
@@ -873,12 +873,12 @@ be accomplished with the following route configuration:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="news" path="/news" methods="GET">
-                <default key="_controller">AppBundle:Main:news</default>
+            <route id="api_show_post" path="/api/posts/{id}" methods="GET|HEAD">
+                <default key="_controller">AppBundle:BlogApi:show</default>
             </route>
 
-            <route id="contact_form" path="/contact" methods="GET|POST">
-                <default key="_controller">AppBundle:Main:contactForm</default>
+            <route id="api_edit_post" path="/api/posts/{id}" methods="PUT">
+                <default key="_controller">AppBundle:BlogApi:edit</default>
             </route>
         </routes>
 
@@ -889,24 +889,25 @@ be accomplished with the following route configuration:
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('news', new Route('/news', array(
-            '_controller' => 'AppBundle:Main:contact',
-        ), array(), array(), '', array(), array('GET')));
+        $collection->add('api_show_post', new Route('/api/posts/{id}', array(
+            '_controller' => 'AppBundle:BlogApi:show',
+        ), array(), array(), '', array(), array('GET', 'HEAD')));
 
-        $collection->add('contact_form', new Route('/contact', array(
-            '_controller' => 'AppBundle:Main:contactForm',
-        ), array(), array(), '', array(), array('GET', 'POST')));
+        $collection->add('api_edit_post', new Route('/api/posts/{id}', array(
+            '_controller' => 'AppBundle:BlogApi:edit',
+        ), array(), array(), '', array(), array('PUT')));
 
         return $collection;
 
 .. versionadded:: 2.2
     The ``methods`` option was introduced in Symfony 2.2. Use the ``_method``
     requirement in older versions.
 
-Despite the fact that these two routes have identical paths (``/contact``),
-the first route will match only GET requests and the second route will match
-only POST requests. This means that you can display the form and submit the
-form via the same URL, while using distinct controllers for the two actions.
+Despite the fact that these two routes have identical paths
+(``/api/posts/{id}``), the first route will match only GET or HEAD requests and
+the second route will match only PUT requests. This means that you can display
+and edit the post with the same URL, while using distinct controllers for the
+two actions.
 
 .. note::