Update voters.rst

ThomasLandauer · web-flow · commit bb0872a149cf · 2020-04-17T14:26:02.000+02:00
Trying to merge the suggestions of 4 people ;-)

What's really odd is that on this dedicated voters page, the reader is referred to someplace else for more info on voters ;-)

&gt; Take a look at the authorization article for an even deeper understanding on voters.

So in the long run, these two should be merged - or at least the voters part integrated into this page.
diff --git a/security/voters.rst b/security/voters.rst
@@ -6,19 +6,30 @@
 How to Use Voters to Check User Permissions
 ===========================================
 
-Security voters are the most granular way of checking permissions (e.g. "can this
-specific user edit the given item?"). This article explains voters in detail.
+Voters are Symfony's most powerful way of managing permissions. They allow you
+to centralize all permission logic, then reuse them in many places.
+
+However, if you don't reuse permissions or your rules are basic, you can always
+put that logic directly into your controller instead. Here's an example how
+this could look like, if you want to make a route accessible to the "owner" only::
+
+    // src/AppBundle/Controller/PostController.php
+    // ...
+
+    if ($post->getOwner() !== $this->getUser()) {
+        throw $this->createAccessDeniedException();
+    }
+
+In that sense, the following example used throughout this page is more like a
+minimal example for voters, rather than a real-world use case.
 
 .. tip::
 
     Take a look at the
     :doc:`authorization </components/security/authorization>`
     article for an even deeper understanding on voters.
 
-How Symfony Uses Voters
------------------------
-
-In order to use voters, you have to understand how Symfony works with them.
+Here's how Symfony works with voters:
 All voters are called each time you use the ``isGranted()`` method on Symfony's
 authorization checker or call ``denyAccessUnlessGranted`` in a controller (which
 uses the authorization checker), or by
@@ -31,21 +42,6 @@ in the application, which can be: affirmative, consensus or unanimous.
 For more information take a look at
 :ref:`the section about access decision managers <components-security-access-decision-manager>`.
 
-.. tip::
-
-    The example used throughout this page features just two routes (``post_show`` and ``post_edit``).
-    However, the advantage of voters is that you can reuse them in *many* places and centralize
-    all permission logic. If you don't reuse permissions or the rules are basic, you instead
-    might want to do the check in the controller directly and throw an ``AccessDeniedException``
-    to create the correct response::
-
-        // src/AppBundle/Controller/PostController.php
-        // ...
-
-        if ($post->getOwner() !== $this->getUser()) {
-            throw $this-> createAccessDeniedException();
-        }
-
 The Voter Interface
 -------------------
 
