adding how to declare new roles

refs #573 @0h30 adding documentation
This commit is contained in:
Julien Fastré 2015-09-29 10:51:38 +02:00
parent fdddf77a90
commit cb48b020f7

View File

@ -129,12 +129,17 @@ Those methods are intentionnaly build to give information about user rights:
Adding your own roles
=====================
.. warning::
This part is not fully implemented. The signature of the abstract class :class:`Chill\\Security\\Authorization\\ChillVoter` will change in the future.
Extending Chill will requires you to define your own roles and rules for your entities. You will have to define your own voter to do so.
To create your own roles, you should:
* implement your own voter. This voter will have to extends the :class:`Chill\\MainBundle\\Security\\AbstractChillVoter`. As defined by Symfony, this voter must be declared as a service and tagged with `security.voter`;
* declare the role through implementing a service tagged with `chill.role` and implementing :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`.
.. note::
Both operation may be done through a simple class: you can implements :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface` and :class:`Chill\\MainBundle\\Security\\AbstractChillVoter` on the same class. See live example: :class:`Chill\\ActivityBundle\\Security\\Authorization\\ActivityVoter`, and similar examples in the `PersonBundle` and `ReportBundle`.
.. seealso::
`How to Use Voters to Check User Permissions <http://symfony.com/doc/current/cookbook/security/voters_data_permission.html>`_
@ -146,8 +151,71 @@ Extending Chill will requires you to define your own roles and rules for your en
From the symfony blog
Declare your role
------------------
To create your own roles, you will have to implement your own voter. This voter will have to extends the :class:`Chill\\MainBundle\\Security\\AbstractChillVoter`. Inside this class, you might use the :class:Chill\\MainBundle\\Security\\Authorization\\AuthorizationHelper to check permission (do not re-invent the wheel). This is a real-world example:
To declare new role, implement the class :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`.
.. code-block:: php
interface ProvideRoleInterface
{
/**
* return an array of role provided by the object
*
* @return string[] array of roles (as string)
*/
public function getRoles();
/**
* return roles which doesn't need
*
* @return string[] array of roles without scopes
*/
public function getRolesWithoutScope();
}
Then declare your service with a tag `chill.role`. Example :
.. code-block:: yaml
your_service:
class: Chill\YourBundle\Security\Authorization\YourVoter
tags:
- { name: chill.role }
Example of an implementation of :class:`Chill\\MainBundle\\Security\\ProvideRoleInterface`:
.. code-block:: php
namespace Chill\PersonBundle\Security\Authorization;
use Chill\MainBundle\Security\ProvideRoleInterface;
class PersonVoter implements ProvideRoleInterface
{
const CREATE = 'CHILL_PERSON_CREATE';
const UPDATE = 'CHILL_PERSON_UPDATE';
const SEE = 'CHILL_PERSON_SEE';
public function getRoles()
{
return array(self::CREATE, self::UPDATE, self::SEE);
}
public function getRolesWithoutScope()
{
return array(self::CREATE, self::UPDATE, self::SEE);
}
}
Implement your voter
--------------------
Inside this class, you might use the :class:`Chill\\MainBundle\\Security\\Authorization\\AuthorizationHelper` to check permission (do not re-invent the wheel). This is a real-world example:
.. code-block:: php