updated docs according to the reviews

Author: Michael Klein

cookbook/security/voter_interface.rst.inc

@@ -0,0 +1,22 @@
+.. code-block:: php
+
+    interface VoterInterface
+    {
+        public function supportsAttribute($attribute);
+        public function supportsClass($class);
+        public function vote(TokenInterface $token, $post, array $attributes);
+    }
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsAttribute` method is used to check if the voter supports
+the given user attribute (i.e: a role, an ACL, etc.).
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsClass` method is used to check if the voter supports the
+class of the object whose access is being checked (doesn't apply to this entry).
+
+The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::vote` method must implement the business logic that verifies whether
+or not the user is granted access. This method must return one of the following
+values:
+
+* ``VoterInterface::ACCESS_GRANTED``: The authorization will be granted by this voter;
+* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if authorization should be granted;
+* ``VoterInterface::ACCESS_DENIED``: The authorization will be denied by this voter.

cookbook/security/voters.rst

@@ -21,28 +21,7 @@ A custom voter must implement
 :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
 which requires the following three methods:
 
-.. code-block:: php
-
-    interface VoterInterface
-    {
-        public function supportsAttribute($attribute);
-        public function supportsClass($class);
-        public function vote(TokenInterface $token, $object, array $attributes);
-    }
-
-The ``supportsAttribute()`` method is used to check if the voter supports
-the given user attribute (i.e: a role, an ACL, etc.).
-
-The ``supportsClass()`` method is used to check if the voter supports the
-class of the object whose access is being checked (doesn't apply to this entry).
-
-The ``vote()`` method must implement the business logic that verifies whether
-or not the user is granted access. This method must return one of the following
-values:
-
-* ``VoterInterface::ACCESS_GRANTED``: The authorization will be granted by this voter;
-* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if authorization should be granted;
-* ``VoterInterface::ACCESS_DENIED``: The authorization will be denied by this voter.
+.. include:: /cookbook/security/voter_interface.rst.inc
 
 In this example, you'll check if the user's IP address matches against a list of
 blacklisted addresses and "something" will be the application. If the user's IP is blacklisted, you'll return

cookbook/security/voters_data_permission.rst

@@ -1,32 +1,31 @@
 .. index::
    single: Security; Data Permission Voters
 
-How to implement your own Voter to check User Permissions for accessing a Given Object
-======================================================================================
+How to Use Voters to Check User Permissions
+===========================================
 
-In Symfony2 you can check the permission to access data by the
+In Symfony2 you can check the permission to access data by using the
 :doc:`ACL module </cookbook/security/acl>`, which is a bit overwhelming
 for many applications. A much easier solution is to work with custom voters,
 which are like simple conditional statements. Voters can be
 also be used to check for permission as a part or even the whole
-application: :doc:`"/cookbook/security/voters"`.
+application: ":doc:`/cookbook/security/voters`".
 
 .. tip::
 
-    Have a look at the pages
-    :doc:`security </cookbook/security>` and
+    Have a look at the chapter
     :doc:`authorization </components/security/authorization>`
-    if you are not familiar with these topics.
+    for a better understanding on voters.
 
-How Symfony uses Voters
+How Symfony Uses Voters
 -----------------------
 
 In order to use voters, you have to understand how Symfony works with them.
 In general, all registered custom voters will be called every time you ask
 Symfony about permissions (ACL). You can use one of three different
 approaches on how to handle the feedback from all voters: affirmative,
 consensus and unanimous. For more information have a look at
-:ref:`"components-security-access-decision-manager"`.
+":ref:`components-security-access-decision-manager`".
 
 The Voter Interface
 -------------------
@@ -35,30 +34,7 @@ A custom voter must implement
 :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
 which has this structure:
 
-// how to put this following snippet (to line 56) in a single file an embed it? as it is used in voters.rst as well.
-
-.. code-block:: php
-
-    interface VoterInterface
-    {
-        public function supportsAttribute($attribute);
-        public function supportsClass($class);
-        public function vote(TokenInterface $token, $post, array $attributes);
-    }
-
-The ``supportsAttribute()`` method is used to check if the voter supports
-the given user attribute (i.e: a role, an acl, etc.).
-
-The ``supportsClass()`` method is used to check if the voter supports the
-current user token class.
-
-The ``vote()`` method must implement the business logic that verifies whether
-or not the user is granted access. This method must return one of the following
-values:
-
-* ``VoterInterface::ACCESS_GRANTED``: The user is allowed to access the application
-* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if the user is granted or not
-* ``VoterInterface::ACCESS_DENIED``: The user is not allowed to access the application
+.. include:: /cookbook/security/voter_interface.rst.inc
 
 In this example, you'll check if the user will have access to a specific
 object according to your custom conditions (e.g. he must be the owner of
@@ -70,9 +46,7 @@ does not belong to this voter, it will return ``VoterInterface::ACCESS_ABSTAIN``
 Creating the Custom Voter
 -------------------------
 
-You could store your Voter to check permission for the view and edit action like following.
-
-.. code-block:: php
+You could store your Voter to check permission for the view and edit action like the following::
 
     // src/Acme/DemoBundle/Security/Authorization/Entity/PostVoter.php
     namespace Acme\DemoBundle\Security\Authorization\Entity;
@@ -100,7 +74,6 @@ You could store your Voter to check permission for the view and edit action like
 
             foreach ($array as $item) {
                 if ($obj instanceof $item))
-
                     return true;
                 }
             }
@@ -113,7 +86,9 @@ You could store your Voter to check permission for the view and edit action like
         {
             // check if voter is used correct, only allow one attribute for a check
             if(count($attributes) !== 1 || !is_string($attributes[0])) {
-                throw new PreconditionFailedHttpException('The Attribute was not set correct. Maximum 1 attribute.');
+                throw new PreconditionFailedHttpException(
+                    'Only one attribute is allowed for VIEW or EDIT'
+                );
             }
 
             // set the attribute to check against
@@ -123,43 +98,42 @@ You could store your Voter to check permission for the view and edit action like
             $user = $token->getUser();
 
             // check if class of this object is supported by this voter
-            if (!($this->supportsClass($post))) {
-
+            if (!$this->supportsClass($post)) {
                 return VoterInterface::ACCESS_ABSTAIN;
             }
 
             // check if the given attribute is covered by this voter
             if (!$this->supportsAttribute($attribute)) {
-
                 return VoterInterface::ACCESS_ABSTAIN;
             }
 
             // check if given user is instance of user interface
-            if (!($user instanceof UserInterface)) {
-
+            if (!$user instanceof UserInterface) {
                 return VoterInterface::ACCESS_DENIED;
             }
 
             switch($attribute) {
                 case 'view':
-                    // the data object could have for e.g. a method isPrivate() which checks the the boolean attribute $private
+                    // the data object could have for e.g. a method isPrivate()
+                    // which checks the Boolean attribute $private
                     if (!$post->isPrivate()) {
-
                         return VoterInterface::ACCESS_GRANTED;
                     }
                     break;
 
                 case 'edit':
-                    // we assume that our data object has a method getOwner() to get the current owner user entity for this data object
+                    // we assume that our data object has a method getOwner() to
+                    // get the current owner user entity for this data object
                     if ($user->getId() === $post->getOwner()->getId()) {
-
                         return VoterInterface::ACCESS_GRANTED;
                     }
                     break;
 
                 default:
                     // otherwise throw an exception, which will break the request
-                    throw new PreconditionFailedHttpException('The Attribute "'.$attribute.'" was not found.')
+                    throw new PreconditionFailedHttpException(
+                        'The Attribute "'.$attribute.'" was not found.'
+                    );
             }
 
         }
@@ -171,8 +145,8 @@ the security layer. This can be done easily through the service container.
 Declaring the Voter as a Service
 --------------------------------
 
-To inject the voter into the security layer, you must declare it as a service,
-and tag it as a "security.voter":
+To inject the voter into the security layer, you must declare it as a service
+and tag it as a ´security.voter´:
 
 .. configuration-block::
 
@@ -202,12 +176,17 @@ and tag it as a "security.voter":
     .. code-block:: php
 
         $container
-            ->register('security.access.post_document_voter', 'Acme\DemoBundle\Security\Authorization\Document\PostVoter')
+            ->register(
+                    'security.access.post_document_voter',
+                    'Acme\DemoBundle\Security\Authorization\Document\PostVoter'
+                )
             ->addTag('security.voter')
         ;
 
-How to use the Voter in a Controller
+How to Use the Voter in a Controller
 ------------------------------------
+The registered voter will then always be asked as soon the method isGranted from
+the security context is called.
 
 .. code-block:: php
 
@@ -222,14 +201,14 @@ How to use the Voter in a Controller
         public function showAction($id)
         {
             // keep in mind, this will call all registered security voters
-            if (false === $this->get('security.context')->isGranted('view')) {
+            if (false === $this->get('security.context')->isGranted('view', $post)) {
                 throw new AccessDeniedException('Unauthorised access!');
             }
 
             $product = $this->getDoctrine()
                 ->getRepository('AcmeStoreBundle:Post')
                 ->find($id);
 
-            return new Response('<html><body>Headline for Post: '.$post->getName().'</body></html>');
+            return new Response('<h1>'.$post->getName().'</h1>');
         }
     }