fsi/acl

FSi ACL Component

THIS PACKAGE IS DEPRECATED

Do not use this package, as it will not receive any updates and may be deleted in the future., _(*1)

ACL - Comprehensive Access Control List system for PHP

FSi ACL component is a set of interfaces and classes which allows management of Access Control List in PHP. It's based on resources, roles and permissions and can be used to build access control systems of almost any degree of complexity., _(*2)

Basic usage

You must create ACL object, add resources, permissions, etc., _(*3)

``` php <?php, <sub>(*4)</sub>

use FSi\Component\ACL;, <sub>(*5)</sub>

$acl = new ACL(); $acl->addPermission($somePermisssion);, <sub>(*6)</sub>

..., <sub>(*7)</sub>

$acl->addResource($someResource);, <sub>(*8)</sub>

..., <sub>(*9)</sub>

$acl->addRole($someRole);, <sub>(*10)</sub>

..., <sub>(*11)</sub>

$acl->addACE($someACE);, <sub>(*12)</sub>

..., <sub>(*13)</sub>

And finally check access to specific resource:

``` php
<?php

if ($acl->isAllowed($someRole, $someResource, $somePermission)) {

    ...

}

Setup and autoloading

Simply add fsi/acl into composer.json of your project and run composer.phar update or composer.phar install, <sub>(*14)</sub>

``` json { "require": { "fsi/acl": "0.9.*" } }, <sub>(*15)</sub>

## Understanding permissions ##

Permissions are defined as objects implementing ``PermissionInterface`` so virtually every object can act as a permission in the ACL
system. For simple cases there is a factory class ``PermissionSimple`` which represents permissions defined only by an identifier
unique across the ACL (i.e. ``'view'``, ``'edit'``, ``'delete'``, etc.). Permission objects must be registered in the ACL throught
``addPermission()`` method before defining any dependencies to them like access control entries.

## Understanding resources ##

Resources are defined as objects implementing ``ResourceInterface`` so virtually every object can act as a resource in the ACL
system. For simple cases there is a factory class ``ResourceSimple`` which represents resources defined only by an identifier
unique across the ACL (i.e. ``'news'``, ``'article'``, ``'offer'``, etc.). Resources can inherit from other resources in a multiple way.
For example resource A may inherit from three other resources X, Y and Z. Multiple inheritance is usefull if there is a need
to have multiple ways to grant access to specific resource, i.e. access to an object can be granted by granting access to its
class (resource representing this class) or some other object which it's associated with. Simple case is when access to some blog
post should be granted by granting access to the blog section it is associated with. Permission to some resource is granted if
permission to any of its parent resources is granted and permission to any of the parent resources is not revoked.

## Understanding roles ##

Roles are used to aggregate multiple access rights to multiple resources in one place and are defined as objects implementing
``RoleInterface`` so any object can act as a role in the ACL system. For simple cases there is a factory class ``RoleSimple`` which
represents role defined only by an identifier unique across the ACL (i.e. ``'user'``, ``'editor'``, ``'publisher'``, ``'admin'``, etc.).
Roles can inherit from other roles in a multiple way. For example role ``'editor'`` can inherit from roles ``'newsEditor'`` and
``'articleEditor'``. Role has granted permission to some resource if any of its parent roles has granted acces to this resource and
none of them has this permission revoked.

## Understanding Access Control Entries ##

Access Control Entry (ACE) are objects determining if specific permission to specific resource is granted for specific role.
There are two predefined ACE classes ``ACEAllow`` and ``ACEDeny`` which always returns true and false respectively, but any ACE
can be created with some complex logic determining when access is granted and when not.

## usage examples ##

Below is some example of how to use ACL directly:

``` php
<?php

$userRole = RoleSimple::factory('user');
$newsEditorRole = RoleSimple::factory('newsEditor');
$articleEditorRole = RoleSimple::factory('articleEditor');
$publisherRole = RoleSimple::factory('publisher');
$newsResource = ResourceSimple::factory('newsClass');
$articleResource = ResourceSimple::factory('articleClass');
$view = PermissionSimple::factory('view');
$edit = PermissionSimple::factory('edit');
$publish = PermissionSimple::factory('publish');

$acl = new ACL();
$acl->addPermission($view);
$acl->addPermission($edit);
$acl->addPermission($publish);
$acl->addResource($newsResource);
$acl->addResource($articleResource);
$acl->addRole($userRole);
$acl->addRole($newsEditorRole);
$acl->addRole($articleEditorRole);
$acl->addRole($publisherRole, array($userRole, $newsEditorRole, $articleEditorRole));
$acl->addACE(new ACEAllow($userRole, $newsResource, $view));
$acl->addACE(new ACEAllow($userRole, $articleResource, $view));
$acl->addACE(new ACEAllow($newsEditorRole, $newsResource, $edit));
$acl->addACE(new ACEAllow($articleEditorRole, $articleResource, $edit));
$acl->addACE(new ACEDeny($userRole, $newsResource, $publish));
$acl->addACE(new ACEDeny($userRole, $articleResource, $publish));

$acl->isAllowed($publisherRole, $newsResource, $publish)
// returns false

$acl->isAllowed($publisherRole, $articleResource, $publish)
// returns false

$acl->isAllowed($publisherRole, $newsResource, $edit)
// returns true

$acl->isAllowed($publisherRole, $articleResource, $edit)
// returns true

Debugging ACL

Considering complex dependincies between many roles, resources and permissions, it's often hard to trace when and why specific permissions are granted or revoked. In order to make this easier this component has built-in optional logging capabilty which uses Monolog to log every activity that takes place during one call of isAllowed() method. FSi\Component\ACL\ACL class has method setLogger() which takes Monolog\Logger instance as an argument. When logger is set, then messages will be logged to it at two different levels:, <sub>(*16)</sub>

• INFO
  • start of the checking process when isAllowed() method is called()
  • every called ACE rule is logged along with the decision that the rule returned
  • end of the process including the final decision that is returned by isAllowed() method
• DEBUG
  • additional information when walking up the resource tree
  • additional information when walking up the role tree