8000 [#2877][#3138] Proofreading the new voter data permission entry · symfony/symfony-docs@2391758 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2391758

Browse files
weaverryanweaverryan
committed
[#2877][#3138] Proofreading the new voter data permission entry
1 parent 11aead7 commit 2391758

File tree

2 files changed

+30
-20
lines changed

2 files changed

+30
-20
lines changed

‎cookbook/security/voter_interface.rst.inc

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,16 @@
88
}
99

1010
The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsAttribute`
11-
method is used to check if the voter supports the given user attribute (i.e: a role, an ACL, etc.).
11+
method is used to check if the voter supports the given user attribute (i.e:
12+
a role like ``ROLE_USER``, an ACL ``EDIT``, etc.).
1213

1314
The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::supportsClass`
1415
method is used to check if the voter supports the class of the object whose
15-
access is being checked (doesn't apply to this entry).
16+
access is being checked.
1617

1718
The :method:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\VoterInterface::vote`
1819
method must implement the business logic that verifies whether or not the
19-
user is granted access. This method must return one of the following values:
20+
user has access. This method must return one of the following values:
2021

2122
* ``VoterInterface::ACCESS_GRANTED``: The authorization will be granted by this voter;
2223
* ``VoterInterface::ACCESS_ABSTAIN``: The voter cannot decide if authorization should be granted;

‎cookbook/security/voters_data_permission.rst

Lines changed: 26 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,31 @@ How to Use Voters to Check User Permissions
77
In Symfony2 you can check the permission to access data by using the
88
:doc:`ACL module </cookbook/security/acl>`, which is a bit overwhelming
99
for many applications. A much easier solution is to work with custom voters,
10-
which are like simple conditional statements. Voters can also be used to
11-
check for permission to a part or even of the whole application:
12-
":doc:`/cookbook/security/voters`".
10+
which are like simple conditional statements.
11+
12+
.. seealso::
13+
14+
Voters can also be used in other ways, like, for example, blacklisting IP
15+
addresses from the entire application: ":doc:`/cookbook/security/voters`".
1316

1417
.. tip::
1518

16-
Have a look at the
19+
Take a look at the
1720
:doc:`authorization </components/security/authorization>`
18-
chapter for a better understanding on voters.
21+
chapter for an even deeper understanding on voters.
1922

2023
How Symfony Uses Voters
2124
-----------------------
2225

2326
In order to use voters, you have to understand how Symfony works wi 8000 th them.
24-
In general, all registered custom voters will be called every time you ask
25-
Symfony about permissions (ACL). You can use one of three different
26-
approaches on how to handle the feedback from all voters: affirmative,
27-
consensus and unanimous. For more information have a look at
28-
":ref:`the section about access decision managers <components-security-access-decision-manager>`".
27+
All voters are called each time you use the ``isGranted()`` method on Symfony's
28+
security context (i.e. the ``security.context`` service). Each decides if
29+
the current user should have access to some resource.
30+
31+
Ultimately, Symfony uses one of three different approaches on what to do
32+
with the feedback from all voters: affirmative, consensus and unanimous.
33+
34+
For more information take a look at ":ref:`the section about access decision managers <components-security-access-decision-manager>`".
2935

3036
The Voter Interface
3137
-------------------
@@ -36,7 +42,7 @@ which has this structure:
3642

3743
.. include:: /cookbook/security/voter_interface.rst.inc
3844

39-
In this example, it'll check if the user will have access to a specific
45+
In this example, the voter will check if the user has access to a specific
4046
object according to your custom conditions (e.g. they must be the owner of
4147
the object). If the condition fails, you'll return
4248
``VoterInterface::ACCESS_DENIED``, otherwise you'll return
@@ -46,7 +52,8 @@ does not belong to this voter, it will return ``VoterInterface::ACCESS_ABSTAIN``
4652
Creating the Custom Voter
4753
-------------------------
4854

49-
You could implement your Voter to check permission for the view and edit action like the following::
55+
The goal is to create a voter that checks to see if a user has access to
56+
view or edit a particular object. Here's an example implementation:
5057

5158
// src/Acme/DemoBundle/Security/Authorization/Voter/PostVoter.php
5259
namespace Acme\DemoBundle\Security\Authorization\Voter;
@@ -87,7 +94,8 @@ You could implement your Voter to check permission for the view and edit action
8794
}
8895
8996
// check if voter is used correct, only allow one attribute for a check
90-
if(1 !== count($attributes) || !is_string($attributes[0])) {
97+
// this isn't a requirement, it's just the way we want our voter to work
98+
if(1 !== count($attributes)) {
9199
throw new InvalidArgumentException(
92100
'Only one attribute is allowed for VIEW or EDIT'
93101
);
@@ -104,14 +112,14 @@ You could implement your Voter to check permission for t 8000 he view and edit action
104112
return VoterInterface::ACCESS_ABSTAIN;
105113
}
106114

107-
// check if given user is instance of user interface
115+
// make sure there is a user object (i.e. that the user is logged in)
108116
if (!$user instanceof UserInterface) {
109117
return VoterInterface::ACCESS_DENIED;
110118
}
111119

112120
switch($attribute) {
113121
case 'view':
114-
// the data object could have for e.g. a method isPrivate()
122+
// the data object could have for example a method isPrivate()
115123
// which checks the Boolean attribute $private
116124
if (!$post->isPrivate()) {
117125
return VoterInterface::ACCESS_GRANTED;
@@ -126,7 +134,6 @@ You could implement your Voter to check permission for the view and edit action
126134
}
127135
break;
128136
}
129-
130137
}
131138
}
132139

@@ -137,7 +144,7 @@ Declaring the Voter as a Service
137144
--------------------------------
138145

139146
To inject the voter into the security layer, you must declare it as a service
140-
and tag it as a ``security.voter``:
147+
and tag it with ``security.voter``:
141148

142149
.. configuration-block::
143150

@@ -212,3 +219,5 @@ from the security context is called.
212219
return new Response('<h1>'.$post->getName().'</h1>');
213220
}
214221
}
222+
223+
It's that easy!

0 commit comments

Comments
 (0)
0