view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    implemented, consuming this role. Entities is a reference implementation
    that can be used by applications, or just taken as an example of an
    ability-based authorization system. Entities::User and Entities::Role
    are the user and role classes that consume the Abilities role in the
    Entities distribution.

  CONSTRAINTS
    Generally, an ability is a yes/no option. Either the user can or can't
    perform a specific action. At times, this might not be flexible enough,
    and the user's ability to perform a certain action should be
    constrained. For example, a user might be granted the ability to edit
    posts in a blog, but this ability should be constrained to the user's
    posts only. The user is not to be allowed to edit posts created by other
    users. "Abilities" supports constraints by allowing to set a name-based
    constraint when granting a user/role a certain ability. Then, checking
    the user's ability to perform an action can include the constraint, for
    example:

            if ($post->{user_id} eq $user->id && $user->can_perform('edit_posts', 'only_his')) {
                    # allow
            } else {
                    # do not allow
            }

    Here, the "Abilities" module allows you to check if the user's ability
    is constrained, but the responsibility for making sure the constraint is
    actually relevant to the case is left to you. In the above example, it
    is the application that checks if the post the user is trying to edit
    was created by them, not the "Abilities" module.

  (PAID) SUBSCRIPTION-BASED WEB SERVICES
    Apart from the scenario described above, this module also provides
    optional support for subscription-based web services, such as those
    where customers subscribe to a certain paid (or free, doesn't matter)
    plan from a list of available plans (GitHub is an example of such a
    service). This functionality is also implemented as a Moo(se) role, in
    the Abilities::Features module provided with this distribution. Read its
    documentation for detailed information.

REQUIRED METHODS
    Classes that consume this role are required to implement the following
    methods:

  roles()
    Returns a list of all role names that a user object belongs to, or a
    role object inherits from.

    Example return structure:

            ( 'moderator', 'supporter' )

    NOTE: In previous versions, this method was required to return an array
    of role objects, not a list of role names. This has been changed in
    version 0.3.

  actions()
    Returns a list of all action names that a user object has been
    explicitely granted, or that a role object has been granted. If a
    certain action is constrained, then it should be added to the list as an
    array reference with two items, the first being the name of the action,
    the second being the name of the constraint.

    Example return structure:

            ( 'create_posts', ['edit_posts', 'only_his'], 'comment_on_posts' )

    NOTE: In previous versions, this method was required to return an array
    of action objects, not a list of action names. This has been changed in
    version 0.3.

  is_super()
    This is a boolean attribute that both user and role objects should have.
    If a user/role object has a true value for this attribute, then they
    will be able to perform any action, even if it wasn't granted to them.

  get_role( $name )
    This is a method that returns the object of the role named $name.

PROVIDED METHODS
    Classes that consume this role will have the following methods available
    to them:

  can_perform( $action, [ $constraint ] )
    Receives the name of an action, and possibly a constraint, and returns a
    true value if the user/role can perform the provided action.

  assigned_role( $role_name )
    This method receives a role name and returns a true value if the
    user/role is a direct member of the provided role. Only direct
    membership is checked, so the user/role must be specifically assigned to
    the provided role, and not to a role that inherits from that role (see
    "does_role( $role )" instead).

  does_role( $role_name )
    Receives the name of a role, and returns a true value if the user/role
    inherits the abilities of the provided role. This method takes
    inheritance into account, so if a user was directly assigned to the
    'admins' role, and the 'admins' role inherits from the 'devs' role, then
    "does_role('devs')" will return true for that user (while
    "assigned_role('devs')" returns false).

  abilities()
    Returns a hash reference of all the abilities a user/role object can
    perform, after consolidating abilities inherited from roles (including
    recursively) and directly granted. Keys in the hash-ref will be names of
    actions, values will be 1 (for yes/no actions) or a single-item
    array-ref with the name of a constraint (for constrained actions).

UPGRADING FROM v0.2
    Up to version 0.2, "Abilities" required the "roles" and "actions"
    attributes to return objects. While this made it easier to calculate
    abilities, it made this system a bit less flexible.

    In version 0.3, "Abilities" changed the requirement such that both these
    attributes need to return strings (the names of the roles/actions). If
    your implementation has granted roles and actions stored in a database
    by names, this made life a bit easier for you. On other implementations,
    however, this has the potential of requiring you to write a bit more
    code. If that is the case, I apologize, but keep in mind that you can
    still store granted roles and actions any way you want in a database
    (either by names or by references), just as long as you correctly