minor #20 Creating the Controller topic (xabbuh)

This PR was squashed before being merged into the 2.7 branch (closes #20).

Discussion
----------

Creating the Controller topic

Commits
-------

ce24865 Creating the Controller topic

Author: javiereguiluz

book/index.rst

@@ -8,7 +8,6 @@ The Book
     from_flat_php_to_symfony2
     installation
     page_creation
-    controller
     routing
     templating
     configuration

book/controller.rst renamed to controller.rst

@@ -791,73 +791,6 @@ There are also special classes to make certain kinds of responses easier:
     ``Request`` and ``Response`` object in the
     :ref:`HttpFoundation component documentation <component-http-foundation-request>`.
 
-Creating Static Pages
----------------------
-
-You can create a static page without even creating a controller (only a route
-and template are needed). See cookbook article
-:doc:`/cookbook/templating/render_without_controller`.
-
-.. index::
-   single: Controller; Forwarding
-
-Forwarding to Another Controller
---------------------------------
-
-Though not very common, you can also forward to another controller
-internally with the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::forward`
-method. Instead of redirecting the user's browser, this makes an "internal" sub-request
-and calls the defined controller. The ``forward()`` method returns the ``Response``
-object that's returned from *that* controller::
-
-    public function indexAction($name)
-    {
-        $response = $this->forward('AppBundle:Something:fancy', array(
-            'name'  => $name,
-            'color' => 'green',
-        ));
-
-        // ... further modify the response or return it directly
-
-        return $response;
-    }
-
-The array passed to the method becomes the arguments for the resulting controller.
-The target controller method might look something like this::
-
-    public function fancyAction($name, $color)
-    {
-        // ... create and return a Response object
-    }
-
-Just like when creating a controller for a route, the order of the arguments of
-``fancyAction()`` doesn't matter: the matching is done by name.
-
-.. _checking-the-validity-of-a-csrf-token:
-
-Validating a CSRF Token
------------------------
-
-Sometimes, you want to use CSRF protection in an action where you don't want to
-use the Symfony Form component. If, for example, you're doing a DELETE action,
-you can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isCsrfTokenValid`
-method to check the CSRF token::
-
-    if ($this->isCsrfTokenValid('token_id', $submittedToken)) {
-        // ... do something, like deleting an object
-    }
-
-.. versionadded:: 2.6
-    The ``isCsrfTokenValid()`` shortcut method was introduced in Symfony 2.6.
-    It is equivalent to executing the following code:
-
-    .. code-block:: php
-
-        use Symfony\Component\Security\Csrf\CsrfToken;
-
-        $this->get('security.csrf.token_manager')
-            ->isTokenValid(new CsrfToken('token_id', 'TOKEN'));
-
 Final Thoughts
 --------------
 
@@ -880,5 +813,3 @@ Learn more from the Cookbook
 
 * :doc:`/cookbook/controller/error_pages`
 * :doc:`/cookbook/controller/service`
-
-.. _`Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php

cookbook/controller/csrf_token_validation.rst

@@ -0,0 +1,17 @@
+.. index::
+    single: Controller; Validating CSRF Tokens
+
+How to Manually Validate a CSRF Token in a Controller
+=====================================================
+
+Sometimes, you want to use CSRF protection in an action where you do not
+want to use the Symfony Form component. If, for example, you are implementing
+a DELETE action, you can use the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::isCsrfTokenValid`
+method to check the validity of a CSRF token::
+
+    public function deleteAction()
+    {
+        if ($this->isCsrfTokenValid('token_id', $submittedToken)) {
+            // ... do something, like deleting an object
+        }
+    }

cookbook/controller/forwarding.rst

@@ -0,0 +1,35 @@
+.. index::
+    single: Controller; Forwarding
+
+How to Forward Requests to another Controller
+=============================================
+
+Though not very common, you can also forward to another controller internally
+with the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::forward`
+method. Instead of redirecting the user's browser, this makes an "internal"
+sub-request and calls the defined controller. The ``forward()`` method returns
+the :class:`Symfony\Component\HttpFoundation\Response` object that is returned
+from *that* controller::
+
+    public function indexAction($name)
+    {
+        $response = $this->forward('AppBundle:Something:fancy', array(
+            'name'  => $name,
+            'color' => 'green',
+        ));
+
+        // ... further modify the response or return it directly
+
+        return $response;
+    }
+
+The array passed to the method becomes the arguments for the resulting controller.
+The target controller method might look something like this::
+
+    public function fancyAction($name, $color)
+    {
+        // ... create and return a Response object
+    }
+
+Just like when creating a controller for a route, the order of the arguments
+of ``fancyAction()`` doesn't matter: the matching is done by name.

cookbook/controller/index.rst

@@ -7,3 +7,5 @@ Controller
     error_pages
     service
     upload_file
+    forwarding
+    csrf_token_validation

cookbook/map.rst.inc

@@ -55,6 +55,8 @@
   * :doc:`/cookbook/controller/error_pages`
   * :doc:`/cookbook/controller/service`
   * :doc:`/cookbook/controller/upload_file`
+  * :doc:`/cookbook/controller/forwarding`
+  * :doc:`/cookbook/controller/csrf_token_validation`
 
 * **Debugging**
 

index.rst

@@ -23,6 +23,16 @@ Get started fast with the Symfony :doc:`Quick Tour <quick_tour/index>`:
 * :doc:`quick_tour/the_controller` >
 * :doc:`quick_tour/the_architecture`
 
+Topics
+------
+
+.. toctree::
+    :hidden:
+
+    controller
+
+* :doc:`/controller`
+
 Book
 ----