Modifications based on feedback by @wouterj and @stof

Author: matthiasnoback

components/security/authentication.rst

@@ -10,9 +10,7 @@ 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 when 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 in the security context::
 
     use Symfony\Component\Security\Http\Firewall\ListenerInterface;
     use Symfony\Component\Security\Core\SecurityContextInterface;
@@ -32,7 +30,9 @@ The listener should then store the authenticated token in the security context:
          */
         private $authenticationManager;
 
-        // string Uniquely identifies the secured area
+        /**
+         * @var string Uniquely identifies the secured area
+         */
         private $providerKey;
 
         // ...
@@ -65,9 +65,7 @@ The listener should then store the authenticated token in the security context:
 The authentication manager
 --------------------------
 
-The default authentication manager is an instance of :class:`Symfony\\Component\\Security\\Core\\Authentication\\AuthenticationProviderManager`:
-
-::
+The default authentication manager is an instance of :class:`Symfony\\Component\\Security\\Core\\Authentication\\AuthenticationProviderManager`::
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationProviderManager;
 
@@ -98,9 +96,10 @@ Authentication providers
 
 Each provider (since it implements
 :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface`)
-has a method ``supports()`` by which the ``AuthenticationProviderManager``
+has a method :method:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface::supports`
+by which the ``AuthenticationProviderManager``
 can determine if it supports the given token. If this is the case, the
-manager then calls the provider's method ``authenticate()``. This method
+manager then calls the provider's method :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\AuthenticationProviderInterface::authenticate`. This method
 should return an authenticated token or throw an :class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`
 (or any other exception extending it).
 
@@ -117,11 +116,10 @@ from the user data storage, hash the password the user has just provided
 the given password is valid.
 
 This functionality is offered by the :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\DaoAuthenticationProvider`.
-It fetches the user's data from a ``UserProvider``, uses a ``PasswordEncoder``
+It fetches the user's data from a :class:`Symfony\\Component\\Security\\Core\\User\\UserProviderInterface``,
+uses a :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
 to create a hash of the password and returns an authenticated token if the
-password was valid.
-
-::
+password was valid::
 
     use Symfony\Component\Security\Core\Authentication\Provider\DaoAuthenticationProvider;
     use Symfony\Component\Security\Core\User\UserChecker;
@@ -162,13 +160,11 @@ password was valid.
 The password encoder factory
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``DaoAuthenticationProvider`` uses an encoder factory to create a password
-encoder for a given type of user. This allows you to use different encoding
-strategies for different types of users.
-The default :class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory`
-receives an array of encoders:
-
-::
+The :class:`Symfony\\Component\\Security\\Core\\Authentication\\Provider\\DaoAuthenticationProvider`
+uses an encoder factory to create a password encoder for a given type of
+user. This allows you to use different encoding strategies for different
+types of users. The default :class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory`
+receives an array of encoders::
 
     use Symfony\Component\Security\Core\Encoder\EncoderFactory;
     use Symfony\Component\Security\Core\Encoder\MessageDigestPasswordEncoder;
@@ -179,7 +175,7 @@ receives an array of encoders:
     $encoders = array(
         'Symfony\\Component\\Security\\Core\\User\\User' => $defaultEncoder,
         'Acme\\Entity\\LegacyUser' => $weakEncoder,
-        ...
+        ...,
     );
 
     $encoderFactory = new EncoderFactory($encoders);
@@ -191,12 +187,10 @@ encoder factory to construct the encoder only when it is needed.
 Password encoders
 ~~~~~~~~~~~~~~~~~
 
-When the ``getEncoder()`` method of the password encoder factory is called
-with the user object as its first argument, it will return an encoder of
-type :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
-which should be used to encode this user's password:
-
-::
+When the :method:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory::getEncoder`
+method of the password encoder factory is called with the user object as
+its first argument, it will return an encoder of type :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`
+which should be used to encode this user's password::
 
     // fetch a user of type Acme\Entity\LegacyUser
     $user = ...

components/security/authorization.rst

@@ -7,8 +7,9 @@ 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\\SecurityContext` using its
-``setToken()`` method.
+in the :class:`Symfony\\Component\\Security\\Core\\SecurityContextInterface`
+using its :method:`Symfony\\Component\\Security\\Core\\SecurityContextInterface::setToken`
+method.
 
 From then on, the user is authenticated, i.e. means identified.
 Now, other parts of the application can use the token to decide whether
@@ -18,19 +19,21 @@ This decision will be made by an instance of :class:`Symfony\\Component\\Securit
 An authorization decision will always be based on a few things:
 
 The current token
-    The token`s ``getRoles()`` method will be used to retrieve the roles
-    of the current user (e.g. "ROLE_SUPER_ADMIN")
+    For instance, the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
+    method may be used to retrieve the roles of the current user (e.g.
+    "ROLE_SUPER_ADMIN"), or a decision may be based on the class of the token.
 A set of attributes
     Each attribute stands for a certain right the user should have, e.g.
     "ROLE_ADMIN" to make sure the user is an administrator.
 An object (optional)
     Any object on which to decide, e.g. the current :class:`Symfony\\Component\\HttpFoundation\\Request`
-    object.
+    object, or an object for which access control needs to be checked, like
+    an article or a comment object.
 
 Access decision manager
 -----------------------
 
-Since choosing whether or not a user is authorized to perform a certain
+Since deciding whether or not a user is authorized to perform a certain
 action can be a complicated process, the standard :class:`Symfony\\Component\\Security\\Core\\Authorization\\AccessDecisionManager`
 itself depends on multiple voters, and makes a final verdict based on all
 the votes (either positive, negative or neutral) it has received. It
@@ -45,7 +48,7 @@ recognizes several strategies:
 ``unanimous``
     Only grant access if none of the voters has denied access
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
 
@@ -61,8 +64,12 @@ recognizes several strategies:
     // whether or not to grant access when there is no majority (applies only to the "consensus" strategy)
     $allowIfEqualGrantedDeniedDecisions = ...;
 
-    $accessDecisionManager = new AccessDecisionManager($voters, $strategy,
-        $allowIfAllAbstainDecisions, $allowIfEqualGrantedDeniedDecisions);
+    $accessDecisionManager = new AccessDecisionManager(
+        $voters,
+        $strategy,
+        $allowIfAllAbstainDecisions,
+        $allowIfEqualGrantedDeniedDecisions
+    );
 
 Voters
 ------
@@ -92,7 +99,7 @@ and "IS_AUTHENTICATED_ANONYMOUSLY" and grants access based on the current
 level of authentication, i.e. is the user fully authenticated, or only based
 on a "remember-me" cookie, or even authenticated anonymously?
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolver;
 
@@ -104,19 +111,20 @@ on a "remember-me" cookie, or even authenticated anonymously?
     $authenticatedVoter = new AuthenticatedVoter($trustResolver);
 
     // instance of Symfony\Component\Security\Core\Authentication\Token\TokenInterface
-    $token = ...
+    $token = ...;
 
     // any object
-    $object = ...
+    $object = ...;
 
     $vote = $authenticatedVoter->vote($token, $object, array('IS_AUTHENTICATED_FULLY');
 
 The :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\RoleVoter`
 supports attributes starting with "ROLE_" and grants access to the user
 when the required "ROLE_*" attributes can all be found in the array of
-roles returned by the token's ``getRoles()`` method.
+roles returned by the token's :method:`Symfony\\Component\\Security\\Core\\Authentication\\Token\\TokenInterface::getRoles`
+method.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Core\Authorization\Voter\RoleVoter;
 
@@ -133,7 +141,7 @@ user to have the "ROLE_ADMIN" role, it grants access to users who in fact
 have the "ROLE_ADMIN" role, but also to users having the "ROLE_SUPER_ADMIN"
 role.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Core\Authorization\Voter\RoleHierarchyVoter;
     use Symfony\Component\Security\Core\Role\RoleHierarchy;
@@ -156,11 +164,10 @@ Roles
 
 Roles are objects that give expression to a certain right the user has.
 The only requirement is that they implement :class:`Symfony\\Component\\Security\\Core\\Role\\RoleInterface`,
-which means they should also have a ``getRole()`` method that returns a
-string representation of the role itself. The default :class:`Symfony\\Component\\Security\\Core\\Role\\Role`
-simply returns its first constructor argument:
-
-::
+which means they should also have a :method:`Symfony\\Component\\Security\\Core\\Role\\Role\\RoleInterface::getRole`
+method that returns a string representation of the role itself. The default
+:class:`Symfony\\Component\\Security\\Core\\Role\\Role` simply returns its
+first constructor argument::
 
     use Symfony\Component\Security\Core\Role\Role;
 
@@ -191,7 +198,7 @@ It uses an access map (which should be an instance of :class:`Symfony\\Component
 which contains request matchers and a corresponding set of attributes that
 are required for the current user to get access to the application.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Http\AccessMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
@@ -201,23 +208,31 @@ are required for the current user to get access to the application.
     $requestMatcher = new RequestMatcher('^/admin');
     $accessMap->add($requestMatcher, array('ROLE_ADMIN'));
 
-    $accessListener = new AccessListener($securityContext, $accessDecisionManager,
-        $accessMap, $authenticationManager);
+    $accessListener = new AccessListener(
+        $securityContext,
+        $accessDecisionManager,
+        $accessMap,
+        $authenticationManager
+    );
 
 Security context
 ~~~~~~~~~~~~~~~~
 
 The access decision manager is also available to other parts of the application
-by means of the ``isGranted($attribute)`` method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
+by means of the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
+method of the :class:`Symfony\\Component\\Security\\Core\\SecurityContext`.
 A call to this method will directly delegate the question to the access
 decision manager.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\SecurityContext;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
 
-    $securityContext = new SecurityContext();
+    $securityContext = new SecurityContext(
+        $authenticationManager,
+        $accessDecisionManager
+    );
 
     if (!$securityContext->isGranted('ROLE_ADMIN')) {
         throw new AccessDeniedException();

components/security/firewall.rst

@@ -10,7 +10,7 @@ steps in the process of authenticating the user have been taken successfully,
 the security context may be asked if the authenticated user has access
 to a certain action or resource of the application.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\SecurityContext;
     use Symfony\Component\Security\Core\Exception\AccessDeniedException;
@@ -36,7 +36,7 @@ ability to find out if the current request points to a secured area.
 The listeners are then asked if the current request can be used to authenticate
 the user.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Http\FirewallMap;
     use Symfony\Component\HttpFoundation\RequestMatcher;
@@ -56,12 +56,13 @@ the user.
 The firewall map will be given to the firewall as it's first argument, together
 with the event dispatcher that is used by the :class:`Symfony\\Component\\HttpKernel\\HttpKernel`.
 
-::
+.. code-block:: php
 
     use Symfony\Component\Security\Http\Firewall;
     use Symfony\Component\HttpKernel\KernelEvents;
 
-    // $dispatcher is the EventDispatcher used by the HttpKernel
+    // the EventDispatcher used by the HttpKernel
+    $dispatcher = ...;
 
     $firewall = new Firewall($map, $dispatcher);
 
@@ -78,27 +79,27 @@ Firewall listeners
 ------------------
 
 When the firewall gets notified of the ``kernel.request`` event, it asks
-the firewall map if the request matches any of the secured areas. If it
-does, the corresponding listeners (who each implement
-:class:`Symfony\\Component\\Security\\Http\\Firewall\\ListenerInterface`)
-will be asked to handle the current request. This basically means: find
-out if the current request contains any information by which the user might
-be authenticated (for instance the Basic HTTP authentication listener checks
-if the request has a header called "PHP_AUTH_USER").
+the firewall map if the request matches one of the secured areas. The first
+secured area that matches the request, will return a set of corresponding
+firewall listeners (which each implement :class:`Symfony\\Component\\Security\\Http\\Firewall\\ListenerInterface`).
+These listeners will all be asked to handle the current request. This basically
+means: find out if the current request contains any information by which
+the user might be authenticated (for instance the Basic HTTP authentication
+listener checks if the request has a header called "PHP_AUTH_USER").
 
 Exception listener
 ------------------
 
-If any of the listeners throws an :class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`
-(or any exception extending this exception), the exception listener that
-was provided when adding secured areas to the firewall map will jump in.
+If any of the listeners throws an :class:`Symfony\\Component\\Security\\Core\\Exception\\AuthenticationException`,
+the exception listener that was provided when adding secured areas to the
+firewall map will jump in.
 
 The exception listener determines what happens next, based on the arguments
 it received when it was created. It may start the authentication procedure,
 maybe ask the user to supply his credentials again (when he has only been
 authenticated based on a "remember-me" cookie), or transform the exception
 into an :class:`Symfony\\Component\\HttpKernel\\Exception\\AccessDeniedHttpException`,
-which will eventually result in an "HTTP/1.1 401: Access Denied" response.
+which will eventually result in an "HTTP/1.1 403: Access Denied" response.
 
 Entry points
 ------------
@@ -107,10 +108,10 @@ When the user is not authenticated at all (i.e. when the security context
 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`,
-which has only one method: ``start()``. This method receives the
-current :class:`Symfony\\Component\\HttpFoundation\\Request` object and
-the exception by which the exception listener was triggered. The method
-should return a :class:`Symfony\\Component\\HttpFoundation\\Response` object,
-for instance the page containing the login form, or in the case of Basic
-HTTP authentication a response with a "WWW-Authenticate" header, which will
-prompt the user to supply his username and password.
+which has only one method: :method:`Symfony\\Component\\Security\\Http\\EntryPoint\\AuthenticationEntryPointInterface::start`.
+This method receives the current :class:`Symfony\\Component\\HttpFoundation\\Request`
+object and the exception by which the exception listener was triggered.
+The method should return a :class:`Symfony\\Component\\HttpFoundation\\Response`
+object, for instance the page containing the login form, or in the case
+of Basic HTTP authentication a response with a "WWW-Authenticate" header,
+which will prompt the user to supply his username and password.