minor #21040 [Security] Update the main voters article (javiereguiluz)

This PR was merged into the 6.4 branch.

Discussion
----------

[Security] Update the main voters article

I propose to add a proper section for cacheable voters ... and move another section because it's a more common use case than the last section of the article.

Commits
-------

3fd1265 [Security] Update the main voters article

Author: javiereguiluz

security/voters.rst

@@ -50,14 +50,6 @@ which makes creating a voter even easier::
 
 .. _how-to-use-the-voter-in-a-controller:
 
-.. tip::
-
-    Checking each voter several times can be time consuming for applications
-    that perform a lot of permission checks. To improve performance in those cases,
-    you can make your voters implement the :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\CacheableVoterInterface`.
-    This allows the access decision manager to remember the attribute and type
-    of subject supported by the voter, to only call the needed voters each time.
-
 Setup: Checking for Access in a Controller
 ------------------------------------------
 
@@ -296,6 +288,89 @@ If you're using the :ref:`default services.yaml configuration <service-container
 you're done! Symfony will automatically pass the ``security.helper``
 service when instantiating your voter (thanks to autowiring).
 
+Improving Voter Performance
+---------------------------
+
+If your application defines many voters and checks permissions on many objects
+during a single request, this can impact performance. Most of the time, voters
+only care about specific permissions (attributes), such as ``EDIT_BLOG_POST``,
+or specific object types, such as ``User`` or ``Invoice``. That's why Symfony
+can cache the voter resolution (i.e. the decision to apply or skip a voter for
+a given attribute or object).
+
+To enable this optimization, make your voter implement
+:class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\CacheableVoterInterface`.
+This is already the case when extending the abstract ``Voter`` class shown above.
+Then, override one or both of the following methods::
+
+    use App\Entity\Post;
+    use Symfony\Component\Security\Core\Authorization\Voter\Voter;
+    // ...
+
+    class PostVoter extends Voter
+    {
+        const VIEW = 'view';
+        const EDIT = 'edit';
+
+        protected function supports(string $attribute, mixed $subject): bool
+        {
+            // ...
+        }
+
+        protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token): bool
+        {
+            // ...
+        }
+
+        // this method returns true if the voter applies to the given attribute;
+        // if it returns false, Symfony won't call it again for this attribute
+        public function supportsAttribute(string $attribute): bool
+        {
+            return in_array($attribute, [self::VIEW, self::EDIT], true);
+        }
+
+        // this method returns true if the voter applies to the given object class/type;
+        // if it returns false, Symfony won't call it again for that type of object
+        public function supportsAttribute(string $attribute): bool
+        {
+            // you can't use a simple Post::class === $subjectType comparison
+            // because the subject type might be a Doctrine proxy class
+            return is_a($subjectType, Post::class, true);
+        }
+    }
+
+.. _security-voters-change-message-and-status-code:
+
+Changing the message and status code returned
+---------------------------------------------
+
+By default, the ``#[IsGranted]`` attribute will throw a
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
+and return an http **403** status code with **Access Denied** as message.
+
+However, you can change this behavior by specifying the message and status code returned::
+
+    // src/Controller/PostController.php
+
+    // ...
+    use Symfony\Component\Security\Http\Attribute\IsGranted;
+
+    class PostController extends AbstractController
+    {
+        #[Route('/posts/{id}', name: 'post_show')]
+        #[IsGranted('show', 'post', 'Post not found', 404)]
+        public function show(Post $post): Response
+        {
+            // ...
+        }
+    }
+
+.. tip::
+
+    If the status code is different than 403, an
+    :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpException`
+    will be thrown instead.
+
 .. _security-voters-change-strategy:
 
 Changing the Access Decision Strategy
@@ -467,35 +542,3 @@ must implement the :class:`Symfony\\Component\\Security\\Core\\Authorization\\Ac
                 // ...
             ;
         };
-
-.. _security-voters-change-message-and-status-code:
-
-Changing the message and status code returned
----------------------------------------------
-
-By default, the ``#[IsGranted]`` attribute will throw a
-:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
-and return an http **403** status code with **Access Denied** as message.
-
-However, you can change this behavior by specifying the message and status code returned::
-
-    // src/Controller/PostController.php
-
-    // ...
-    use Symfony\Component\Security\Http\Attribute\IsGranted;
-
-    class PostController extends AbstractController
-    {
-        #[Route('/posts/{id}', name: 'post_show')]
-        #[IsGranted('show', 'post', 'Post not found', 404)]
-        public function show(Post $post): Response
-        {
-            // ...
-        }
-    }
-
-.. tip::
-
-    If the status code is different than 403, an
-    :class:`Symfony\\Component\\HttpKernel\\Exception\\HttpException`
-    will be thrown instead.