From b610beb0cf2f9d5c0e68a153bfbb10dff3dc3dfe Mon Sep 17 00:00:00 2001
From: Wouter de Jong <wouter@wouterj.nl>
Date: Sat, 11 Apr 2020 20:13:26 +0200
Subject: [PATCH] Describe voters a bit more prominent in the Security guide

---
 security.rst | 53 +++++++++++++++++++++++++---------------------------
 1 file changed, 25 insertions(+), 28 deletions(-)

diff --git a/security.rst b/security.rst
index 5aa5000b9cb..8cf4a8e4666 100644
--- a/security.rst
+++ b/security.rst
@@ -376,20 +376,24 @@ generated earlier, the roles are an array that's stored in the database, and
 every user is *always* given at least one role: ``ROLE_USER``::
 
     // src/Entity/User.php
-    // ...
-
-    /**
-     * @ORM\Column(type="json")
-     */
-    private $roles = [];
 
-    public function getRoles(): array
+    // ...
+    class User
     {
-        $roles = $this->roles;
-        // guarantee every user at least has ROLE_USER
-        $roles[] = 'ROLE_USER';
+        /**
+         * @ORM\Column(type="json")
+         */
+        private $roles = [];
 
-        return array_unique($roles);
+        // ...
+        public function getRoles(): array
+        {
+            $roles = $this->roles;
+            // guarantee every user at least has ROLE_USER
+            $roles[] = 'ROLE_USER';
+
+            return array_unique($roles);
+        }
     }
 
 This is a nice default, but you can do *whatever* you want to determine which roles
@@ -644,6 +648,16 @@ Securing other Services
 
 See :doc:`/security/securing_services`.
 
+Securing Individual Objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most applications require more specific access rules. For instance, a user
+should be able to only edit their own comments on a blog. Voters allow you
+to write *whatever* business logic you need to determine access. Using
+these voters is similar to the role-based access checks implemented in the
+previous chapters. Read :doc:`/security/voters` to learn how to implement
+your own voter.
+
 Checking to see if a User is Logged In (IS_AUTHENTICATED_FULLY)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -681,22 +695,6 @@ like this:
   this - this is useful when *whitelisting* URLs to guarantee access - some
   details are in :doc:`/security/access_control`.
 
-.. _security-secure-objects:
-
-Access Control Lists (ACLs): Securing individual Database Objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Imagine you are designing a blog where users can comment on your posts. You
-also want a user to be able to edit their own comments, but not those of
-other users. Also, as the admin user, you want to be able to edit *all* comments.
-
-:doc:`Voters </security/voters>` allow you to write *whatever* business logic you
-need (e.g. the user can edit this post because they are the creator) to determine
-access. That's why voters are officially recommended by Symfony to create ACL-like
-security systems.
-
-If you still prefer to use traditional ACLs, refer to the `Symfony ACL bundle`_.
-
 .. _retrieving-the-user-object:
 
 5a) Fetching the User Object
@@ -1032,6 +1030,5 @@ Authorization (Denying Access)
 
 .. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
 .. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle
-.. _`Symfony ACL bundle`: https://github.com/symfony/acl-bundle
 .. _`Symfony Security screencast series`: https://symfonycasts.com/screencast/symfony-security
 .. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html