Skip to content

Commit 14ce4c7

Browse files
author
Iltar van der Berg
committed
Updated documentation regarding the SecurityContext split; symfony/symfony#11690 
1 parent 51224e9 commit 14ce4c7

File tree

14 files changed

+168
-99
lines changed

14 files changed

+168
-99
lines changed

‎book/security.rst‎

Lines changed: 32 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -438,7 +438,7 @@ Next, create the controller that will display the login form::
438438

439439
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
440440
use Symfony\Component\HttpFoundation\Request;
441-
use Symfony\Component\Security\Core\SecurityContextInterface;
441+
use Symfony\Component\Security\Core\Security;
442442

443443
class SecurityController extends Controller
444444
{
@@ -447,19 +447,19 @@ Next, create the controller that will display the login form::
447447
$session = $request->getSession();
448448

449449
// get the login error if there is one
450-
if ($request->attributes->has(SecurityContextInterface::AUTHENTICATION_ERROR)) {
450+
if ($request->attributes->has(Security::AUTHENTICATION_ERROR)) {
451451
$error = $request->attributes->get(
452-
SecurityContextInterface::AUTHENTICATION_ERROR
452+
Security::AUTHENTICATION_ERROR
453453
);
454-
} elseif (null !== $session && $session->has(SecurityContextInterface::AUTHENTICATION_ERROR)) {
455-
$error = $session->get(SecurityContextInterface::AUTHENTICATION_ERROR);
456-
$session->remove(SecurityContextInterface::AUTHENTICATION_ERROR);
454+
} elseif (null !== $session && $session->has(Security::AUTHENTICATION_ERROR)) {
455+
$error = $session->get(Security::AUTHENTICATION_ERROR);
456+
$session->remove(Security::AUTHENTICATION_ERROR);
457457
} else {
458458
$error = '';
459459
}
460460

461461
// last username entered by the user
462-
$lastUsername = (null === $session) ? '' : $session->get(SecurityContextInterface::LAST_USERNAME);
462+
$lastUsername = (null === $session) ? '' : $session->get(Security::LAST_USERNAME);
463463

464464
return $this->render(
465465
'AcmeSecurityBundle:Security:login.html.twig',
@@ -713,7 +713,7 @@ see :doc:`/cookbook/security/form_login`.
713713
``/login_check`` doesn't match any firewall, you'll receive a ``Unable
714714
to find the controller for path "/login_check"`` exception.
715715

716-
**4. Multiple firewalls don't share security context**
716+
**4. Multiple firewalls don't share the same context**
717717

718718
If you're using multiple firewalls and you authenticate against one firewall,
719719
you will *not* be authenticated against any other firewalls automatically.
@@ -1174,7 +1174,7 @@ authorization from inside a controller::
11741174

11751175
public function helloAction($name)
11761176
{
1177-
if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
1177+
if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
11781178
throw $this->createAccessDeniedException('Unable to access this page!');
11791179
}
11801180

@@ -1186,6 +1186,10 @@ authorization from inside a controller::
11861186
.. versionadded:: 2.5
11871187
The ``createAccessDeniedException`` method was introduced in Symfony 2.5.
11881188

1189+
.. versionadded:: 2.6
1190+
The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
1191+
to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
1192+
11891193
The :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::createAccessDeniedException`
11901194
method creates a special :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
11911195
object, which ultimately triggers a 403 HTTP response inside Symfony.
@@ -1621,14 +1625,18 @@ Retrieving the User Object
16211625
~~~~~~~~~~~~~~~~~~~~~~~~~~
16221626

16231627
After authentication, the ``User`` object of the current user can be accessed
1624-
via the ``security.context`` service. From inside a controller, this will
1628+
via the ``security.token_storage`` service. From inside a controller, this will
16251629
look like::
16261630

16271631
public function indexAction()
16281632
{
1629-
$user = $this->get('security.context')->getToken()->getUser();
1633+
$user = $this->get('security.token_storage')->getToken()->getUser();
16301634
}
16311635

1636+
.. versionadded:: 2.6
1637+
The ``security.token_storage`` service was introduced in Symfony 2.6. Prior
1638+
to Symfony 2.6, you had to use the ``getToken()`` method of the ``security.context`` service.
1639+
16321640
In a controller this can be shortcut to:
16331641

16341642
.. code-block:: php
@@ -1898,13 +1906,17 @@ authorization from inside a controller::
18981906

18991907
public function helloAction($name)
19001908
{
1901-
if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
1909+
if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
19021910
throw new AccessDeniedException();
19031911
}
19041912

19051913
// ...
19061914
}
19071915

1916+
.. versionadded:: 2.6
1917+
The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
1918+
to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
1919+
19081920
.. caution::
19091921

19101922
A firewall must be active or an exception will be thrown when the ``isGranted()``
@@ -1928,7 +1940,7 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
19281940

19291941
public function indexAction()
19301942
{
1931-
if (!$this->get('security.context')->isGranted(new Expression(
1943+
if (!$this->get('security.authorization_checker')->isGranted(new Expression(
19321944
'"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
19331945
))) {
19341946
throw new AccessDeniedException();
@@ -1937,6 +1949,10 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
19371949
// ...
19381950
}
19391951

1952+
.. versionadded:: 2.6
1953+
The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
1954+
to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
1955+
19401956
In this example, if the current user has ``ROLE_ADMIN`` or if the current
19411957
user object's ``isSuperAdmin()`` method returns ``true``, then access will
19421958
be granted (note: your User object may not have an ``isSuperAdmin`` method,
@@ -1982,10 +1998,10 @@ Additionally, you have access to a number of functions inside the expression:
19821998
use Symfony\Component\ExpressionLanguage\Expression;
19831999
// ...
19842000

1985-
$sc = $this->get('security.context');
1986-
$access1 = $sc->isGranted('IS_AUTHENTICATED_REMEMBERED');
2001+
$authorizationChecker = $this->get('security.authorization_checker');
2002+
$access1 = $authorizationChecker->isGranted('IS_AUTHENTICATED_REMEMBERED');
19872003

1988-
$access2 = $sc->isGranted(new Expression(
2004+
$access2 = $authorizationChecker->isGranted(new Expression(
19892005
'is_remember_me() or is_fully_authenticated()'
19902006
));
19912007

‎book/templating.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1166,6 +1166,12 @@ automatically:
11661166
<p>Application Environment: <?php echo $app->getEnvironment() ?></p>
11671167
<?php endif ?>
11681168

1169+
.. versionadded:: 2.6
1170+
The global ``app.security`` variable (or the ``$app->getSecurity()``
1171+
method in PHP templates) is deprecated as of Symfony 2.6. Use `app.user`
1172+
(`$app->getUser()`) and `is_granted()` (`$view['security']->isGranted()`)
1173+
instead.
1174+
11691175
.. tip::
11701176

11711177
You can add your own global template variables. See the cookbook example

‎components/security/authentication.rst‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,32 @@
44
Authentication
55
==============
66

7+
.. versionadded:: 2.6
8+
The ``TokenStorageInterface`` was introduced in Symfony 2.6. Prior, you
9+
had to use the ``getToken()`` method of the
10+
:class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`.
11+
712
When a request points to a secured area, and one of the listeners from the
813
firewall map is able to extract the user's credentials from the current
914
:class:`Symfony\\Component\\HttpFoundation\\Request` object, it should create
1015
a token, containing these credentials. The next thing the listener should
1116
do is ask the authentication manager to validate the given token, and return
1217
an *authenticated* token if the supplied credentials were found to be valid.
13-
The listener should then store the authenticated token in the security context::
18+
The listener should then store the authenticated token using
19+
:class:`the token storage <Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface>`::
1420

1521
use Symfony\Component\Security\Http\Firewall\ListenerInterface;
16-
use Symfony\Component\Security\Core\SecurityContextInterface;
22+
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
1723
use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
1824
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
1925
use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
2026

2127
class SomeAuthenticationListener implements ListenerInterface
2228
{
2329
/**
24-
* @var SecurityContextInterface
30+
* @var TokenStorageInterface
2531
*/
26-
private $securityContext;
32+
private $tokenStorage;
2733

2834
/**
2935
* @var AuthenticationManagerInterface
@@ -54,7 +60,7 @@ The listener should then store the authenticated token in the security context::
5460
->authenticationManager
5561
->authenticate($unauthenticatedToken);
5662

57-
$this->securityContext->setToken($authenticatedToken);
63+
$this->tokenStorage->setToken($authenticatedToken);
5864
}
5965
}
6066

‎components/security/authorization.rst‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ Authorization
77
When any of the authentication providers (see :ref:`authentication_providers`)
88
has verified the still-unauthenticated token, an authenticated token will
99
be returned. The authentication listener should set this token directly
10-
in the :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`
11-
using its :method:`Symfony\\Component\\Security\\Core\\SecurityContextInterface::setToken`
10+
in the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface`
11+
using its :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorageInterface::setToken`
1212
method.
1313

1414
From then on, the user is authenticated, i.e. identified. Now, other parts
@@ -29,6 +29,11 @@ An authorization decision will always be based on a few things:
2929
Any object for which access control needs to be checked, like
3030
an article or a comment object.
3131

32+
.. versionadded:: 2.6
33+
The ``TokenStorageInterface`` was introduced in Symfony 2.6. Prior, you
34+
had to use the ``setToken()`` method of the
35+
:class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`.
36+
3237
.. _components-security-access-decision-manager:
3338

3439
Access Decision Manager
@@ -227,23 +232,24 @@ are required for the current user to get access to the application::
227232
$authenticationManager
228233
);
229234

230-
Security Context
231-
~~~~~~~~~~~~~~~~
235+
Authorization Checker
236+
~~~~~~~~~~~~~~~~~~~~~
232237

233238
The access decision manager is also available to other parts of the application
234-
via the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
235-
method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
239+
via the :method:`Symfony\\Component\\Security\\Core\\Authorization\\AuthorizationChecker::isGranted`
240+
method of the :class:`Symfony\\Component\\Security\\Core\\Authorization\\AuthorizationChecker`.
236241
A call to this method will directly delegate the question to the access
237242
decision manager::
238243

239-
use Symfony\Component\Security\SecurityContext;
244+
use Symfony\Component\Security\Core\Authorization\AuthorizationChecker;
240245
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
241246

242-
$securityContext = new SecurityContext(
247+
$authorizationChecker = new AuthorizationChecker(
248+
$tokenStorage,
243249
$authenticationManager,
244250
$accessDecisionManager
245251
);
246252

247-
if (!$securityContext->isGranted('ROLE_ADMIN')) {
253+
if (!$authorizationChecker->isGranted('ROLE_ADMIN')) {
248254
throw new AccessDeniedException();
249255
}

‎components/security/firewall.rst‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,11 @@ certain action or resource of the application::
3030
throw new AccessDeniedException();
3131
}
3232

33+
.. versionadded:: 2.6
34+
As of Symfony 2.6, the :class:`Symfony\\Component\\Security\\Core\\SecurityContext` class was split
35+
in the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Authorization\\AuthorizationChecker` and
36+
:class:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\Storage\\TokenStorage` classes.
37+
3338
.. note::
3439

3540
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.
115120
Entry Points
116121
~~~~~~~~~~~~
117122

118-
When the user is not authenticated at all (i.e. when the security context
123+
When the user is not authenticated at all (i.e. when the token storage
119124
has no token yet), the firewall's entry point will be called to "start"
120125
the authentication process. An entry point should implement
121126
:class:`Symfony\\Component\\Security\\Http\\EntryPoint\\AuthenticationEntryPointInterface`,

0 commit comments

Comments
 (0)