Minor tweaks

Author: javiereguiluz

security.rst

@@ -2715,8 +2715,8 @@ anonymous users access by checking if there is no user set on the token::
 
 .. versionadded:: 7.3
 
-    The `$vote` parameter in the :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::voteOnAttribute` method
-    was introduced in Symfony 7.3.
+    The ``$vote`` argument of the ``voteOnAttribute()`` method was introduced
+    in Symfony 7.3.
 
 Setting Individual User Permissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

security/voters.rst

@@ -51,8 +51,8 @@ which makes creating a voter even easier::
 
 .. versionadded:: 7.3
 
-    The `$vote` parameter in the :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::voteOnAttribute` method
-    was introduced in Symfony 7.3.
+    The ``$vote`` argument of the ``voteOnAttribute()`` method was introduced
+    in Symfony 7.3.
 
 .. _how-to-use-the-voter-in-a-controller:
 
@@ -173,11 +173,10 @@ would look like this::
         protected function voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null): bool
         {
             $user = $token->getUser();
-            $vote ??= new Vote();
 
             if (!$user instanceof User) {
                 // the user must be logged in; if not, deny access
-                $vote->reasons[] = 'The user is not logged in.';
+                $vote?->addReason('The user is not logged in.');
                 return false;
             }
 
@@ -205,12 +204,15 @@ would look like this::
 
         private function canEdit(Post $post, User $user): bool
         {
-            // this assumes that the Post object has a `getOwner()` method
-            if ($user === $post->getOwner()) {
+            // this assumes that the Post object has a `getAuthor()` method
+            if ($user === $post->getAuthor()) {
                 return true;
             }
 
-            $vote->reasons[] = 'You are not the owner of the Post.';
+            $vote?->addReason(sprintf(
+                'The logged in user (username: %s) is not the author of this post (id: %d).',
+                $user->getUsername(), $post->getId()
+            ));
 
             return false;
         }
@@ -233,9 +235,9 @@ To recap, here's what's expected from the two abstract methods:
 ``voteOnAttribute(string $attribute, mixed $subject, TokenInterface $token, ?Vote $vote = null)``
     If you return ``true`` from ``supports()``, then this method is called. Your
     job is to return ``true`` to allow access and ``false`` to deny access.
-    The ``$token`` can be used to find the current user object (if any). The ``$vote``
-    argument can be used to add a reason to the vote. In this example, all of the
-    complex business logic is included to determine access.
+    The ``$token`` can be used to find the current user object (if any).
+    The ``$vote`` argument can be used to provide an explanation for the vote.
+    This explanation is included in log messages and on exception pages.
 
 .. _declaring-the-voter-as-a-service: