Rebased "add shortcut methods"

book/controller.rst

@@ -429,25 +429,33 @@ A great way to see the core functionality in action is to look in the
 Redirecting
 ~~~~~~~~~~~
 
-If you want to redirect the user to another page, use the
-:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::redirect`
-method::
+If you want to redirect the user to another page, use the ``redirectToRoute()`` method::
 
     public function indexAction()
     {
-        return $this->redirect($this->generateUrl('homepage'));
+        return $this->redirectToRoute('homepage');
+
+        // redirectToRoute is equivalent to using redirect() and generateUrl() together:
+        // return $this->redirect($this->generateUrl('homepage'), 301);
     }
 
-The ``generateUrl()`` method is just a helper function that generates the URL
-for a given route. For more information, see the :doc:`Routing </book/routing>`
-chapter.
+.. versionadded:: 2.6
+    The ``redirectToRoute()`` method was added in Symfony 2.6. Previously (and still now), you
+    could use ``redirect()`` and ``generateUrl()`` together for this (see the example below).
+
+Or, if you want to redirect externally, just use ``redirect()`` and pass it the URL::
+
+    public function indexAction()
+    {
+        return $this->redirect('http://symfony.com/doc');
+    }
 
-By default, the ``redirect()`` method performs a 302 (temporary) redirect. To
+By default, the ``redirectToRoute()`` method performs a 302 (temporary) redirect. To
 perform a 301 (permanent) redirect, modify the second argument::
 
     public function indexAction()
     {
-        return $this->redirect($this->generateUrl('homepage'), 301);
+        return $this->redirectToRoute('homepage', 301);
     }
 
 .. tip::
@@ -623,12 +631,14 @@ For example, imagine you're processing a form submit::
         if ($form->isValid()) {
             // do some sort of processing
 
-            $request->getSession()->getFlashBag()->add(
+            $this->addFlash(
                 'notice',
                 'Your changes were saved!'
             );
 
-            return $this->redirect($this->generateUrl(...));
+            // $this->addFlash is equivalent to $this->get('session')->getFlashBag()->add
+
+            return $this->redirectToRoute(...);
         }
 
         return $this->render(...);
@@ -638,8 +648,8 @@ After processing the request, the controller sets a ``notice`` flash message
 in the session and then redirects. The name (``notice``) isn't significant -
 it's just something you invent and reference next.
 
-In the template of the next page (or even better, in your base layout template),
-the following code will render the ``notice`` message:
+In the template of the next action, the following code could be used to render
+the ``notice`` message:
 
 .. configuration-block::
 

book/doctrine.rst

@@ -667,7 +667,7 @@ you have a route that maps a product id to an update action in a controller::
         $product->setName('New product name!');
         $em->flush();
 
-        return $this->redirect($this->generateUrl('homepage'));
+        return $this->redirectToRoute('homepage');
     }
 
 Updating an object involves just three steps:

book/forms.rst

@@ -234,7 +234,7 @@ controller::
         if ($form->isValid()) {
             // perform some action, such as saving the task to the database
 
-            return $this->redirect($this->generateUrl('task_success'));
+            return $this->redirectToRoute('task_success');
         }
 
         // ...
@@ -319,7 +319,7 @@ querying if the "Save and add" button was clicked::
             ? 'task_new'
             : 'task_success';
 
-        return $this->redirect($this->generateUrl($nextAction));
+        return $this->redirectToRoute($nextAction);
     }
 
 .. index::
@@ -1233,7 +1233,7 @@ it after a form submission can be done when the form is valid::
         $em->persist($task);
         $em->flush();
 
-        return $this->redirect($this->generateUrl('task_success'));
+        return $this->redirectToRoute('task_success');
     }
 
 If, for some reason, you don't have access to your original ``$task`` object,

book/propel.rst

@@ -234,7 +234,7 @@ have a route that maps a product id to an update action in a controller::
         $product->setName('New product name!');
         $product->save();
 
-        return $this->redirect($this->generateUrl('homepage'));
+        return $this->redirectToRoute('homepage');
     }
 
 Updating an object involves just three steps:

book/security.rst

@@ -813,23 +813,25 @@ You can easily deny access from inside a controller::
 
     public function helloAction($name)
     {
-        if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
-            throw $this->createAccessDeniedException();
-        }
+        // The second parameter is used to specify on what object the role is tested.
+        $this->denyAccessUnlessGranted('ROLE_ADMIN', null, 'Unable to access this page!');
+
+        // Old way :
+        // if (false === $this->isGranted('ROLE_ADMIN')) {
+        //     throw $this->createAccessDeniedException('Unable to access this page!');
+        // }
 
         // ...
     }
 
 .. versionadded:: 2.6
-     The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
-     to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
-
-.. versionadded:: 2.5
-    The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
+    The ``denyAccessUnlessGranted()`` method was introduced in Symfony 2.6. Previously (and
+    still now), you could check access directly and throw the ``AccessDeniedException`` as shown
+    in the example above).
 
-The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException`
-method creates a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
-object, which ultimately triggers a 403 HTTP response inside Symfony.
+In both cases, a special
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
+is thrown, which ultimately triggers a 403 HTTP response inside Symfony.
 
 That's it! If the user isn't logged in yet, they will be asked to login (e.g.
 redirected to the login page). If they *are* logged in, they'll be shown

book/validation.rst

@@ -231,7 +231,7 @@ workflow looks like the following from inside a controller::
         if ($form->isValid()) {
             // the validation passed, do something with the $author object
 
-            return $this->redirect($this->generateUrl(...));
+            return $this->redirectToRoute(...);
         }
 
         return $this->render('BlogBundle:Author:form.html.twig', array(

components/form/introduction.rst

@@ -587,7 +587,7 @@ method:
 
                 // ... perform some action, such as saving the data to the database
 
-                return $this->redirect($this->generateUrl('task_success'));
+                return $this->redirectToRoute('task_success');
             }
 
             // ...

cookbook/doctrine/file_uploads.rst

@@ -244,7 +244,7 @@ The following controller shows you how to handle the entire process::
             $em->persist($document);
             $em->flush();
 
-            return $this->redirect($this->generateUrl(...));
+            return $this->redirectToRoute(...);
         }
 
         return array('form' => $form->createView());
@@ -267,7 +267,7 @@ in a moment to handle the file upload::
         $em->persist($document);
         $em->flush();
 
-        return $this->redirect(...);
+        return $this->redirectToRoute(...);
     }
 
 The ``upload()`` method will take advantage of the :class:`Symfony\\Component\\HttpFoundation\\File\\UploadedFile`
@@ -432,7 +432,7 @@ call to ``$document->upload()`` should be removed from the controller::
         $em->persist($document);
         $em->flush();
 
-        return $this->redirect(...);
+        return $this->redirectToRoute(...);
     }
 
 .. note::

cookbook/doctrine/registration_form.rst

@@ -287,7 +287,7 @@ the validation and saves the data into the database::
             $em->persist($registration->getUser());
             $em->flush();
 
-            return $this->redirect(...);
+            return $this->redirectToRoute(...);
         }
 
         return $this->render(

cookbook/expression/expressions.rst

@@ -33,11 +33,9 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
 
     public function indexAction()
     {
-        if (!$this->get('security.authorization_checker')->isGranted(new Expression(
+        $this->denyAccessUnlessGranted(new Expression(
             '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
-        ))) {
-            throw $this->createAccessDeniedException();
-        }
+        ));
 
         // ...
     }

cookbook/form/direct_submit.rst

@@ -25,7 +25,7 @@ submissions::
         if ($form->isValid()) {
             // perform some action...
 
-            return $this->redirect($this->generateUrl('task_success'));
+            return $this->redirectToRoute('task_success');
         }
 
         return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
@@ -66,7 +66,7 @@ method, pass the submitted data directly to
             if ($form->isValid()) {
                 // perform some action...
 
-                return $this->redirect($this->generateUrl('task_success'));
+                return $this->redirectToRoute('task_success');
             }
         }
 
@@ -111,7 +111,7 @@ a convenient shortcut to the previous example::
             if ($form->isValid()) {
                 // perform some action...
 
-                return $this->redirect($this->generateUrl('task_success'));
+                return $this->redirectToRoute('task_success');
             }
         }
 

cookbook/form/form_collections.rst

@@ -717,7 +717,7 @@ the relationship between the removed ``Tag`` and ``Task`` object.
                 $em->flush();
 
                 // redirect back to some edit page
-                return $this->redirect($this->generateUrl('task_edit', array('id' => $id)));
+                return $this->redirectToRoute('task_edit', array('id' => $id));
             }
 
             // render some form template

cookbook/security/remember_me.rst

@@ -162,19 +162,11 @@ In the following example, the action is only allowed if the user has the
 
     public function editAction()
     {
-        if (false === $this->get('security.authorization_checker')->isGranted(
-            'IS_AUTHENTICATED_FULLY'
-           )) {
-            throw new AccessDeniedException();
-        }
+        $this->denyAccessUnlessGranted('IS_AUTHENTICATED_FULLY');
 
         // ...
     }
 
-.. versionadded:: 2.6
-    The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
-    to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
-
 If your application is based on the Symfony Standard Edition, you can also secure
 your controller using annotations:
 

cookbook/security/securing_services.rst

@@ -14,17 +14,11 @@ and checking the current user's role::
 
     public function helloAction($name)
     {
-        if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
-            throw new AccessDeniedException();
-        }
+        $this->denyAccessUnlessGranted('ROLE_ADMIN');
 
         // ...
     }
 
-.. versionadded:: 2.6
-    The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
-    to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
-
 You can also secure *any* service in a similar way by injecting the ``security.authorization_checker``
 service into it. For a general introduction to injecting dependencies into
 services see the :doc:`/book/service_container` chapter of the book. For