NAME
   Abilities - Simple, hierarchical user authorization for web
   applications, with optional support for plan-based paid services.

VERSION
   version 0.1

SYNOPSIS
           package User;

           use Moose;
           with 'Abilities';

           # ... define required methods ...

           # somewhere else in your code:

           # get a user object that consumed the Abilities role
           my $user = MyApp->get_user('username'); # $user is a User object

           # check if the user is able to do something
           if ($user->can_perform('something')) {
                   do_something();
           } else {
                   die "Hey you can't do that, you can only do ", join(', ', $user->abilities);
           }

DESCRIPTION
   Abilities is a simple yet powerful mechanism for authorizing users of
   web applications to perform certain actions in the app's code. This is
   an extension of the familiar role-based access control that is common in
   various systems and frameworks like Catalyst (See
   Catalyst::Plugin::Authorization::Roles for the role-based implementation
   and Catalyst::Plugin::Authorization::Abilities for the ability-based
   implementation that inspired this module).

   As opposed to the role-based access control - where users are allowed
   access to a certain feature (here called 'action') only through their
   association to a certain role that is hard-coded in the program's code -
   in ability-based acccess control, a list of actions is assigned to every
   user, and they are only allowed to perform these actions. Actions are
   not assigned by the developer during development, but rather by the
   end-user during deployment. This allows for much more flexibility, and
   also speeds up development, as you (the developer) do not need to think
   about who should be allowed to perform a certain action, and can easily
   grant access later-on after deployment (assuming you're also the
   end-user).

   Abilities to perform certain actions can be given to a user
   specifically, or via roles the user can assume (as in role-based access
   control). For example, if user 'user01' is a member of role 'admin', and
   this user wishes to perform some action, for example 'delete_foo', then
   they will only be able to do so if the 'delete_foo' ability was given to
   either the user itself or the 'admin' role itself. Furthermore, roles
   can be assigned other roles; for example, roles 'mods' and 'editors' can
   be assigned _inside_ role 'mega_mods'. Users of the 'mega_mods' role
   will assume all actions owned by the 'mods' and 'editors' roles.

   A commonly known use-case for this type of access control is message
   boards, where the administrator might wish to create roles with certain
   actions and associate users with the roles (more commonly called 'user
   groups'); for example, the admin can create an 'editor' role, giving
   users of this role the ability to edit and delete posts, but not any
   other administrative action. So in essence, this type of access control
   relieves the developer from deciding who gets to do what and passes
   these decisions to the end-user, which might be necessary in certain
   situations.

   The Abilities module is implemented as a Moose role. In order to be able
   to use this mechanism, web applications must implement a user management
   system that will consume this role. More specifically, a user class and
   a role class must be implemented, consuming this role. Entities is a
   reference implementation that can be used by web applications, or just
   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.

 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 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 roles that a user object belongs to, or a role
   object inherits from. The list must contain references to the role
   objects, not just their names.

 actions()
   Returns a list of all actions that a user object has been explicitely
   granted, or that a role object has been granted. The list must contain
   references to the action objects, not just their names.

 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.

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

 can_perform( $action_name | @action_names )
   Receives the name of an action (or names of actions), and returns a true
   value if the user/role can perform the provided action(s). If more than
   one actions are passed, a true value will be returned only if the
   user/role can perform ALL of these actions.

 belongs_to( $role_name | @role_names )
 takes_from( $role_name | @role_names )
   The above two methods are actually the same. The names are meant to
   differentiate between user objects (first case) and role objects (second
   case).

   These methods receive a role name (or names). In case of a user object,
   the method will return a true value if the user is a direct member of
   the provided role. In case multiple role names were provided, a true
   value will be returned only if the user is a member of ALL of these
   roles. Only direct association is checked, so the user must be
   specifically assigned to the provided role, and not to a role that
   inherits from that role (see "inherits_from_role()" instead.

   In case of a role object, this method will return a true value if the
   role directly consumes the abilities of the provided role. In case
   multiple role names were provided, a true value will be returned only if
   the role directly consumes ALL of these roles. Like in case of a user,
   only direct association is checked, so inheritance doesn't count.

 inherits_from_role( $role_name | @role_names )
   Receives the name of a role (or names of roles), and returns a true
   value if the user/role inherits the abilities of the provided role. If
   more than one roles are passed, a true value will be returned only if
   the user/role inherits from ALL of these roles.

   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 inherits_from_role('devs') will return true for that
   user.

 all_abilities()
   Returns a list of all actions that a user/role can perform, either due
   to direct association or due to inheritance.

INTERNAL METHODS
   These methods are only to be used internally.

 _all_abilities()
TODO
   *   Create tests

       Create tests for these roles. Right now the only way this is
       actually tested is through the Entities distribution tests.

   *   Catalyst::Plugin::Authorization::Abilities

       Find a way to make Catalyst::Plugin::Authorization::Abilities use
       this role.

AUTHOR
   Ido Perlmuter, "<ido at ido50 dot net>"

BUGS
   Please report any bugs or feature requests to "bug-abilities at
   rt.cpan.org", or through the web interface at
   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Abilities>. I will be
   notified, and then you'll automatically be notified of progress on your
   bug as I make changes.

SUPPORT
   You can find documentation for this module with the perldoc command.

       perldoc Abilities

   You can also look for information at:

   *   RT: CPAN's request tracker

       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Abilities>

   *   AnnoCPAN: Annotated CPAN documentation

       <http://annocpan.org/dist/Abilities>

   *   CPAN Ratings

       <http://cpanratings.perl.org/d/Abilities>

   *   Search CPAN

       <http://search.cpan.org/dist/Abilities/>

LICENSE AND COPYRIGHT
   Copyright 2010 Ido Perlmuter.

   This program is free software; you can redistribute it and/or modify it
   under the terms of either: the GNU General Public License as published
   by the Free Software Foundation; or the Artistic License.

   See http://dev.perl.org/licenses/ for more information.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.