minor #13554 Explaining controllers as viable alternative (ThomasLandauer, wouterj)

xabbuh · xabbuh · commit b90336bed46c · 2020-08-03T10:22:06.000+02:00
This PR was merged into the 3.4 branch. Discussion ---------- Explaining controllers as viable alternative See #13406 (comment) Please wrap it in a "caution" box, or whatever you think is appropriate. I'm unsure about how much context of the controller should be shown in the code, since the entire controller is only shown later. If you think it's too confusing now, I'd suggest to show the controller as "skeleton" above this note. Commits ------- 15c4adc Update voters.rst bb0872a Update voters.rst 577dfa2 Update voters.rst fdfd1ad Update security/voters.rst 221bbb1 Update voters.rst 164aec4 [#13554] Slightly reworded the tip 2bc5c54 Update voters.rst 40bbd81 Explaining controllers as viable alternative
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 a minimal
+example for voters.
 
 .. 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
