Updated documentation regarding the SecurityContext split; symfony/symfony#11690

Author: Iltar van der Berg

book/security.rst

@@ -438,7 +438,7 @@ Next, create the controller that will display the login form::
 
     use Symfony\Bundle\FrameworkBundle\Controller\Controller;
     use Symfony\Component\HttpFoundation\Request;
-    use Symfony\Component\Security\Core\SecurityContextInterface;
+    use Symfony\Component\Security\Core\SecuritySessionStorageInterface;
 
     class SecurityController extends Controller
     {
@@ -447,19 +447,19 @@ Next, create the controller that will display the login form::
             $session = $request->getSession();
 
             // get the login error if there is one
-            if ($request->attributes->has(SecurityContextInterface::AUTHENTICATION_ERROR)) {
+            if ($request->attributes->has(SecuritySessionStorageInterface::AUTHENTICATION_ERROR)) {
                 $error = $request->attributes->get(
-                    SecurityContextInterface::AUTHENTICATION_ERROR
+                    SecuritySessionStorageInterface::AUTHENTICATION_ERROR
                 );
-            } elseif (null !== $session && $session->has(SecurityContextInterface::AUTHENTICATION_ERROR)) {
-                $error = $session->get(SecurityContextInterface::AUTHENTICATION_ERROR);
-                $session->remove(SecurityContextInterface::AUTHENTICATION_ERROR);
+            } elseif (null !== $session && $session->has(SecuritySessionStorageInterface::AUTHENTICATION_ERROR)) {
+                $error = $session->get(SecuritySessionStorageInterface::AUTHENTICATION_ERROR);
+                $session->remove(SecuritySessionStorageInterface::AUTHENTICATION_ERROR);
             } else {
                 $error = '';
             }
 
             // last username entered by the user
-            $lastUsername = (null === $session) ? '' : $session->get(SecurityContextInterface::LAST_USERNAME);
+            $lastUsername = (null === $session) ? '' : $session->get(SecuritySessionStorageInterface::LAST_USERNAME);
 
             return $this->render(
                 'AcmeSecurityBundle:Security:login.html.twig',
@@ -713,7 +713,7 @@ see :doc:`/cookbook/security/form_login`.
     ``/login_check`` doesn't match any firewall, you'll receive a ``Unable
     to find the controller for path "/login_check"`` exception.
 
-    **4. Multiple firewalls don't share security context**
+    **4. Multiple firewalls don't share the same context**
 
     If you're using multiple firewalls and you authenticate against one firewall,
     you will *not* be authenticated against any other firewalls automatically.
@@ -1174,7 +1174,7 @@ authorization from inside a controller::
 
     public function helloAction($name)
     {
-        if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
+        if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
             throw $this->createAccessDeniedException('Unable to access this page!');
         }
 
@@ -1186,6 +1186,10 @@ authorization from inside a controller::
 .. versionadded:: 2.5
     The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
 
+.. 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.
+
 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.
@@ -1622,14 +1626,18 @@ Retrieving the User Object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After authentication, the ``User`` object of the current user can be accessed
-via the ``security.context`` service. From inside a controller, this will
+via the ``security.token_storage`` service. From inside a controller, this will
 look like::
 
     public function indexAction()
     {
-        $user = $this->get('security.context')->getToken()->getUser();
+        $user = $this->get('security.token_storage')->getToken()->getUser();
     }
 
+.. versionadded:: 2.6
+    The ``security.token_storage`` service was introduced in Symfony 2.6. Prior
+    to Symfony 2.6, you had to use the ``getToken()`` method of the ``security.context`` service.
+
 In a controller this can be shortcut to:
 
 .. code-block:: php
@@ -1899,13 +1907,17 @@ authorization from inside a controller::
 
     public function helloAction($name)
     {
-        if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
+        if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
             throw new AccessDeniedException();
         }
 
         // ...
     }
 
+.. 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.
+
 .. caution::
 
     A firewall must be active or an exception will be thrown when the ``isGranted()``
@@ -1929,7 +1941,7 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
 
     public function indexAction()
     {
-        if (!$this->get('security.context')->isGranted(new Expression(
+        if (!$this->get('security.authorization_checker')->isGranted(new Expression(
             '"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
         ))) {
             throw new AccessDeniedException();
@@ -1938,6 +1950,10 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
         // ...
     }
 
+.. 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.
+
 In this example, if the current user has ``ROLE_ADMIN`` or if the current
 user object's ``isSuperAdmin()`` method returns ``true``, then access will
 be granted (note: your User object may not have an ``isSuperAdmin`` method,
@@ -1983,10 +1999,10 @@ Additionally, you have access to a number of functions inside the expression:
         use Symfony\Component\ExpressionLanguage\Expression;
         // ...
 
-        $sc = $this->get('security.context');
-        $access1 = $sc->isGranted('IS_AUTHENTICATED_REMEMBERED');
+        $authorizationChecker = $this->get('security.authorization_checker');
+        $access1 = $authorizationChecker->isGranted('IS_AUTHENTICATED_REMEMBERED');
 
-        $access2 = $sc->isGranted(new Expression(
+        $access2 = $authorizationChecker->isGranted(new Expression(
             'is_remember_me() or is_fully_authenticated()'
         ));
 

book/templating.rst

@@ -1155,6 +1155,10 @@ automatically:
             <p>Application Environment: <?php echo $app->getEnvironment() ?></p>
         <?php endif; ?>
 
+.. versionadded:: 2.6
+     The ``app.security`` (or ``$app->getSecurity()``) global is deprecated as of Symfony 2.6. 
+     Use `app.user` (`$app->getUser()`) and `is_granted()` (`$view['security']->isGranted()`) instead.
+
 .. tip::
 
     You can add your own global template variables. See the cookbook example

components/security/authentication.rst

@@ -10,20 +10,20 @@ firewall map is able to extract the user's credentials from the current
 a token, containing these credentials. The next thing the listener should
 do is ask the authentication manager to validate the given token, and return
 an *authenticated* token if the supplied credentials were found to be valid.
-The listener should then store the authenticated token in the security context::
+The listener should then store the authenticated token using the token storage::
 
     use Symfony\Component\Security\Http\Firewall\ListenerInterface;
-    use Symfony\Component\Security\Core\SecurityContextInterface;
+    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
     use Symfony\Component\HttpKernel\Event\GetResponseEvent;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
 
     class SomeAuthenticationListener implements ListenerInterface
     {
         /**
-         * @var SecurityContextInterface
+         * @var TokenStorageInterface
          */
-        private $securityContext;
+        private $tokenStorage;
 
         /**
          * @var AuthenticationManagerInterface
@@ -54,10 +54,15 @@ The listener should then store the authenticated token in the security context::
                 ->authenticationManager
                 ->authenticate($unauthenticatedToken);
 
-            $this->securityContext->setToken($authenticatedToken);
+            $this->tokenStorage->setToken($authenticatedToken);
         }
     }
 
+.. versionadded:: 2.6
+    The :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface` was
+    introduced in Symfony 2.6. Prior, you had to use the ``getToken()`` method of
+    :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`.
+
 .. note::
 
     A token can be of any class, as long as it implements

components/security/authorization.rst

@@ -7,8 +7,8 @@ Authorization
 When any of the authentication providers (see :ref:`authentication_providers`)
 has verified the still-unauthenticated token, an authenticated token will
 be returned. The authentication listener should set this token directly
-in the :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`
-using its :method:`Symfony\\Component\\Security\\Core\\SecurityContextInterface::setToken`
+in the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface`
+using its :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface::setToken`
 method.
 
 From then on, the user is authenticated, i.e. identified. Now, other parts
@@ -227,23 +227,24 @@ are required for the current user to get access to the application::
         $authenticationManager
     );
 
-Security Context
-~~~~~~~~~~~~~~~~
+Authorization Checker
+~~~~~~~~~~~~~~~~~~~~~
 
 The access decision manager is also available to other parts of the application
-via the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
-method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
+via the :method:`Symfony\\Component\\Security\\Core\\Authorization\\AuthorizationChecker::isGranted`
+method of the :class:`Symfony\\Component\\Security\\Core\\Authorization\\AuthorizationChecker`.
 A call to this method will directly delegate the question to the access
 decision manager::
 
-    use Symfony\Component\Security\SecurityContext;
+    use Symfony\Component\Security\Core\Authorization\AuthorizationChecker;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 
-    $securityContext = new SecurityContext(
+    $authorizationChecker = new AuthorizationChecker(
+        $tokenStorage,
         $authenticationManager,
         $accessDecisionManager
     );
 
-    if (!$securityContext->isGranted('ROLE_ADMIN')) {
+    if (!$authorizationChecker->isGranted('ROLE_ADMIN')) {
         throw new AccessDeniedException();
     }

components/security/firewall.rst

@@ -30,6 +30,11 @@ certain action or resource of the application::
         throw new AccessDeniedException();
     }
 
+.. versionadded:: 2.6
+    As of Symfony 2.6, the :class:`Symfony\\Component\\Security\\Core\\SecurityContext` class was split 
+    in the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Authorization\\AuthorizationChecker` and 
+    :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorage` classes.
+
 .. note::
 
     Read the dedicated sections to learn more about :doc:`/components/security/authentication`
@@ -115,7 +120,7 @@ which will eventually result in an "HTTP/1.1 403: Access Denied" response.
 Entry Points
 ~~~~~~~~~~~~
 
-When the user is not authenticated at all (i.e. when the security context
+When the user is not authenticated at all (i.e. when the token storage
 has no token yet), the firewall's entry point will be called to "start"
 the authentication process. An entry point should implement
 :class:`Symfony\\Component\\Security\\Http\\EntryPoint\\AuthenticationEntryPointInterface`,

cookbook/form/dynamic_form_modification.rst

@@ -223,7 +223,7 @@ Using an event listener, your form might look like this::
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\Form\FormEvents;
     use Symfony\Component\Form\FormEvent;
-    use Symfony\Component\Security\Core\SecurityContext;
+    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
     class FriendMessageFormType extends AbstractType
@@ -255,17 +255,17 @@ contains only this user's friends.
 Luckily it is pretty easy to inject a service inside of the form. This can be
 done in the constructor::
 
-    private $securityContext;
+    private $tokenStorage;
 
-    public function __construct(SecurityContext $securityContext)
+    public function __construct(TokenStorageInterface $tokenStorage)
     {
-        $this->securityContext = $securityContext;
+        $this->tokenStorage = $tokenStorage;
     }
 
 .. note::
 
-    You might wonder, now that you have access to the User (through the security
-    context), why not just use it directly in ``buildForm`` and omit the
+    You might wonder, now that you have access to the User (through the token
+    storage), why not just use it directly in ``buildForm`` and omit the
     event listener? This is because doing so in the ``buildForm`` method
     would result in the whole form type being modified and not just this
     one form instance. This may not usually be a problem, but technically
@@ -275,22 +275,22 @@ done in the constructor::
 Customizing the Form Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have all the basics in place you can take advantage of the ``SecurityContext``
+Now that you have all the basics in place you can take advantage of the ``TokenStorageInterface``
 and fill in the listener logic::
 
     // src/Acme/DemoBundle/FormType/FriendMessageFormType.php
 
-    use Symfony\Component\Security\Core\SecurityContext;
+    use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
     use Doctrine\ORM\EntityRepository;
     // ...
 
     class FriendMessageFormType extends AbstractType
     {
-        private $securityContext;
+        private $tokenStorage;
 
-        public function __construct(SecurityContext $securityContext)
+        public function __construct(TokenStorageInterface $tokenStorage)
         {
-            $this->securityContext = $securityContext;
+            $this->tokenStorage = $tokenStorage;
         }
 
         public function buildForm(FormBuilderInterface $builder, array $options)
@@ -301,7 +301,7 @@ and fill in the listener logic::
             ;
 
             // grab the user, do a quick sanity check that one exists
-            $user = $this->securityContext->getToken()->getUser();
+            $user = $this->tokenStorage->getToken()->getUser();
             if (!$user) {
                 throw new \LogicException(
                     'The FriendMessageFormType cannot be used without an authenticated user!'
@@ -336,6 +336,11 @@ and fill in the listener logic::
         // ...
     }
 
+.. versionadded:: 2.6
+    The :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface` was
+    introduced in Symfony 2.6. Prior, you had to use the ``getToken()`` method of
+    :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`.
+
 .. note::
 
     The ``multiple`` and ``expanded`` form options will default to false
@@ -347,7 +352,7 @@ Using the Form
 Our form is now ready to use and there are two possible ways to use it inside
 of a controller:
 
-a) create it manually and remember to pass the security context to it;
+a) create it manually and remember to pass the token storage to it;
 
 or
 
@@ -363,9 +368,9 @@ your new form type in many places or embedding it into other forms::
     {
         public function newAction(Request $request)
         {
-            $securityContext = $this->container->get('security.context');
+            $tokenStorage = $this->container->get('security.token_storage');
             $form = $this->createForm(
-                new FriendMessageFormType($securityContext)
+                new FriendMessageFormType($tokenStorage)
             );
 
             // ...
@@ -386,7 +391,7 @@ it with :ref:`dic-tags-form-type`.
         services:
             acme.form.friend_message:
                 class: Acme\DemoBundle\Form\Type\FriendMessageFormType
-                arguments: ["@security.context"]
+                arguments: ["@security.token_storage"]
                 tags:
                     - { name: form.type, alias: acme_friend_message }
 
@@ -395,7 +400,7 @@ it with :ref:`dic-tags-form-type`.
         <!-- app/config/config.xml -->
         <services>
             <service id="acme.form.friend_message" class="Acme\DemoBundle\Form\Type\FriendMessageFormType">
-                <argument type="service" id="security.context" />
+                <argument type="service" id="security.token_storage" />
                 <tag name="form.type" alias="acme_friend_message" />
             </service>
         </services>
@@ -408,7 +413,7 @@ it with :ref:`dic-tags-form-type`.
         $container->setDefinition(
             'acme.form.friend_message',
             $definition,
-            array('security.context')
+            array('security.token_storage')
         );
 
 If you wish to create it from within a controller or any other service that has