feature #3486 Documenting createAccessDeniedException() method (klaussilveira)

weaverryan · weaverryan · commit 46377b29e8f7 · 2014-02-01T22:29:56.000-06:00
This PR was merged into the master branch. Discussion ---------- Documenting createAccessDeniedException() method Updating documentation to reflect the changes added in symfony/symfony#9405. | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#9405) | Applies to | 2.5+ | Fixed tickets | Commits ------- da6002d Wrapping line b1b9090 Adding versionadded detail 53f156c Updating references to match doc format 6fd3f93 Documenting createAccessDeniedException() method
diff --git a/book/security.rst b/book/security.rst
@@ -1072,19 +1072,25 @@ fine-grained enough in certain cases. When necessary, you can easily force
 authorization from inside a controller::
 
     // ...
-    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 
     public function helloAction($name)
     {
         if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
-            throw new AccessDeniedException();
+            throw $this->createAccessDeniedException('Unable to access this page!');
         }
 
         // ...
     }
 
 .. _book-security-securing-controller-annotations:
 
+.. versionadded:: 2.5
+    The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
+
+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.
+
 Thanks to the SensioFrameworkExtraBundle, you can also secure your controller using annotations::
 
     // ...
