improvements according to the reviews

cookbook/security/voters_data_permission.rst

@@ -1,28 +1,29 @@
 .. index::
  single: Security; Data Permission Voters
 
-How to implement your own Voter to check user permissions for accessing a given object
+How to implement your own Voter to check User Permissions for accessing a Given Object
 ======================================================================================
 
-In Symfony2 you can check the permission to access data by 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
-voters, which are like simple conditional statements. Voters can be 
-also used to check for permission as a part or even the whole 
+In Symfony2 you can check the permission to access data by 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"`.
 
 .. tip::
 
  It is good to understand the basics about what and how
- :doc:`authorization </components/security/authorization>` works.
+ :doc:`authorization </components/security/authorization>` works. // correct link in book?
 
-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). In general there are three different 
-approaches on how to handle the feedback from all voters: 
+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"`.
 
 The Voter Interface
@@ -32,13 +33,13 @@ A custom voter must implement
 :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface`,
 which has this structure:
 
-.. code-block:: php
+.. code-block:: php // :: shortcut? and put the snippet (to line 56) in a single file an reference ?
 
  interface VoterInterface
  {
  public function supportsAttribute($attribute);
  public function supportsClass($class);
- public function vote(TokenInterface $token, $object, array $attributes);
+ public function vote(TokenInterface $token, $post, array $attributes);
  }
 
 The ``supportsAttribute()`` method is used to check if the voter supports
@@ -60,7 +61,7 @@ object according to your custom conditions (e.g. he must be the owner of
 the object). If the condition fails, you'll return
 ``VoterInterface::ACCESS_DENIED``, otherwise you'll return
 ``VoterInterface::ACCESS_GRANTED``. In case the responsibility for this decision
-belongs not to this voter, it will return ``VoterInterface::ACCESS_ABSTAIN``.
+does not belong to this voter, it will return ``VoterInterface::ACCESS_ABSTAIN``.
 
 Creating the Custom Voter
 -------------------------
@@ -72,81 +73,86 @@ You could store your Voter to check permission for the view and edit action like
  // src/Acme/DemoBundle/Security/Authorization/Entity/PostVoter.php
  namespace Acme\DemoBundle\Security\Authorization\Entity;
 
+ use Symfony\Component\HttpKernel\Exception\PreconditionFailedHttpException;
  use Symfony\Component\DependencyInjection\ContainerInterface;
  use Symfony\Component\Security\Core\Authorization\Voter\VoterInterface;
  use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
  use Symfony\Component\Security\Core\User\UserInterface;
+ use Doctrine\Common\Util\ClassUtils;
 
  class PostVoter implements VoterInterface
  {
-
- public function supportsAttribute($attribute) 
+ public function supportsAttribute($attribute)
  {
  return in_array($attribute, array(
  'view',
  'edit',
  ));
  }
- 
- public function supportsClass($class)
+
+ public function supportsClass($obj)
  {
- // could be "Acme\DemoBundle\Entity\Post" as well
- $array = array("Acme\DemoBundle\Entity\Post");
-
+ $array = array('Acme\DemoBundle\Entity\Post');
+
  foreach ($array as $item) {
  // check with stripos in case doctrine is using a proxy class for this object
- if (stripos($s, $item) !== false) {
-
+ // if (stripos($s, $item) !== false) {
+ if ($obj instanceof $item)) // check if this will also check for interfaces etc. like it should be in oop (inheritace)
+ // or return $targetClass === $class || is_subclass_of($class, $targetClass);
  return true;
  }
  }
 
  return false;
  }
-
- public function vote(TokenInterface $token, $object, array $attributes) 
+
+ /** @var \Acme\DemoBundle\Entity\Post $post */
+ public function vote(TokenInterface $token, $post, array $attributes) // remove array
  {
+ // always get the first attribute
+ $attribute = $attributes[0];
+
  // get current logged in user
  $user = $token->getUser();
- 
+
  // check if class of this object is supported by this voter
- if (!($this->supportsClass(get_class($object)))) {
+ if (!($this->supportsClass($post))) { // maybe without ClassUtils::getRealClass(
 
  return VoterInterface::ACCESS_ABSTAIN;
  }
- 
+
  // check if the given attribute is covered by this voter
- foreach ($attributes as $attribute) {
- if (!$this->supportsAttribute($attribute)) {
+ if (!$this->supportsAttribute($attribute)) {
 
- return VoterInterface::ACCESS_ABSTAIN;
- }
+ return VoterInterface::ACCESS_ABSTAIN;
  }
- 
+
  // check if given user is instance of user interface
  if (!($user instanceof UserInterface)) {
 
  return VoterInterface::ACCESS_DENIED;
  }
- 
- switch($this->attributes[0]) {
+
+ switch($attribute) {
  case 'view':
- if ($object->isPrivate() === false) {
+ // the data object could have for e.g. a method isPrivate() which checks the the boolean attribute $private
+ if (!$post->isPrivate()) {
 
  return VoterInterface::ACCESS_GRANTED;
  }
  break;
- 
+
  case 'edit':
- if ($user->getId() === $object->getOwner()->getId()) {
+ // 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 denied access
- return VoterInterface::ACCESS_DENIED;
+ // otherwise throw an exception
+ throw new PreconditionFailedHttpException('The Attribute "'.$attribute.'"" was not found.')
  }
 
  }
@@ -170,6 +176,53 @@ and tag it as a "security.voter":
  security.access.post_voter:
  class: Acme\DemoBundle\Security\Authorization\Entity\PostVoter
  public: false
- # the service gets tagged as a voter
  tags:
- - { name: security.voter }
+ - { name: security.voter }
+
+ .. code-block:: xml
+
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <container xmlns="http://symfony.com/schema/dic/services">
+ <services>
+ <service id="security.access.post_document_voter"
+ class="Acme\DemoBundle\Security\Authorization\Document\PostVoter"
+ public="false">
+ <tag name="security.voter" />
+ </service>
+ </services>
+ </container>
+
+ .. code-block:: php
+
+ $container
+ ->register('security.access.post_document_voter', 'Acme\DemoBundle\Security\Authorization\Document\PostVoter')
+ ->addTag('security.voter')
+ ;
+
+How to use the Voter in a Controller
+------------------------------------
+
+.. code-block:: php
+
+ // src/Acme/DemoBundle/Controller/PostController.php
+ namespace Acme\DemoBundle\Controller;
+
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+
+ class PostController
+ {
+ public function showAction($id)
+ {
+ // keep in mind, this will call all registered security voters
+ if (false === $this->get('security.context')->isGranted('view')) {
+ 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>');
+ }
+ }