Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5363542

Browse files
weaverryanweaverryan
committed
feature #4188 Updated documentation regarding the SecurityContext split (iltar)
This PR was submitted for the master branch but it was merged into the 2.6 branch instead (closes #4188). Discussion ---------- Updated documentation regarding the SecurityContext split | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | >=2.6 | Fixed tickets | symfony/symfony#11690 This PR is to update the documentation regarding my PR on symfony/symfony. I require some feedback regarding: - Code Examples, I did not change *all* examples because the class using the `$securityContext` was not updated in my PR as it's Backwards Compatible - The usage of "security context". The term is correct, but it might get really confusing for people who see that the security context is deprecated. However, this is only regarding the `SecurityContext`, `SecurityContextInterface` and `@security.context`. - The above point is what confused me too so the docs might be out of context in certain spots, please review this thoroughly Commits ------- deff25f Updated documentation regarding the SecurityContext split; symfony/symfony#11690
2 parents 5ef52ee + deff25f commit 5363542

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 security 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.
@@ -1618,14 +1622,18 @@ Retrieving the User Object
16181622
~~~~~~~~~~~~~~~~~~~~~~~~~~
16191623

16201624
After authentication, the ``User`` object of the current user can be accessed
1621-
via the ``security.context`` service. From inside a controller, this will
1625+
via the ``security.token_storage`` service. From inside a controller, this will
16221626
look like::
16231627

16241628
public function indexAction()
16251629
{
1626-
$user = $this->get('security.context')->getToken()->getUser();
1630+
$user = $this->get('security.token_storage')->getToken()->getUser();
16271631
}
16281632

1633+
.. versionadded:: 2.6
1634+
The ``security.token_storage`` service was introduced in Symfony 2.6. Prior
1635+
to Symfony 2.6, you had to use the ``getToken()`` method of the ``security.context`` service.
1636+
16291637
In a controller this can be shortcut to:
16301638

16311639
.. code-block:: php
@@ -1895,13 +1903,17 @@ authorization from inside a controller::
18951903

18961904
public function helloAction($name)
18971905
{
1898-
if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
1906+
if (false === $this->get('security.authorization_checker')->isGranted('ROLE_ADMIN')) {
18991907
throw new AccessDeniedException();
19001908
}
19011909

19021910
// ...
19031911
}
19041912

1913+
.. versionadded:: 2.6
1914+
The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
1915+
to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
1916+
19051917
.. caution::
19061918

19071919
A firewall must be active or an exception will be thrown when the ``isGranted()``
@@ -1925,7 +1937,7 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
19251937

19261938
public function indexAction()
19271939
{
1928-
if (!$this->get('security.context')->isGranted(new Expression(
1940+
if (!$this->get('security.authorization_checker')->isGranted(new Expression(
19291941
'"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
19301942
))) {
19311943
throw new AccessDeniedException();
@@ -1934,6 +1946,10 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
19341946
// ...
19351947
}
19361948

1949+
.. versionadded:: 2.6
1950+
The ``security.authorization_checker`` service was introduced in Symfony 2.6. Prior
1951+
to Symfony 2.6, you had to use the ``isGranted()`` method of the ``security.context`` service.
1952+
19371953
In this example, if the current user has ``ROLE_ADMIN`` or if the current
19381954
user object's ``isSuperAdmin()`` method returns ``true``, then access will
19391955
be granted (note: your User object may not have an ``isSuperAdmin`` method,
@@ -1979,10 +1995,10 @@ Additionally, you have access to a number of functions inside the expression:
19791995
use Symfony\Component\ExpressionLanguage\Expression;
19801996
// ...
19811997

1982-
$sc = $this->get('security.context');
1983-
$access1 = $sc->isGranted('IS_AUTHENTICATED_REMEMBERED');
1998+
$authorizationChecker = $this->get('security.authorization_checker');
1999+
$access1 = $authorizationChecker->isGranted('IS_AUTHENTICATED_REMEMBERED');
19842000

1985-
$access2 = $sc->isGranted(new Expression(
2001+
$access2 = $authorizationChecker->isGranted(new Expression(
19862002
'is_remember_me() or is_fully_authenticated()'
19872003
));
19882004

‎book/templating.rst

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

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

11731179
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)