Simply because none really fitted my needs. I don't for a minute suggest it is inherently better than any others or that you should use this instead of X library - it is just a library that fits my needs.
What makes my needs so incompatible with other libraries? Well, my aims for an ACL are given below. I've not found anything else that was close enough to warrant forking,
especially since one of my core aims is simplicity and small amounts of clear code.
- not require you to manually hard code lists of resources and permission types to be later checked against. All resources should be defined naturally with;
short, functional code, not abstract mappings and list definitions
I will give however credit [Olly Morgan](http://github.com/ollym) for writing such a simple and neat ACL library that, despite ultimately not being quite what I need, inspired me to
This user guide is intended to explain the (hopefully simple) concepts and implementation of AACL. In each section, concepts go first, then implementation then examples.
It should be relatively trivial to modify the library to work with other ORMs but as this is only likely to be used by me for now, a flexible driver system seems unnecessary.
Any PHP class that implements `AACL_Resource` interface is considered a resource. This means that just by implementing it, rules can be added based on that object.
AACL ships with two abstract Resource classes `Controller_AACL` and `Sprig_AACL` which allow any extending controllers or models to automatically become valid resources
This method servers a dual purpose. When the argument `$return_current` is false, the method should return an array of string names, one for each action
- When both arguments are NULL, the function should return an array containing information about any special conditions the resource supports. More on what conditions are below.
The format of this array is `array('condition_id' => 'Nice description for UIs')`.
-**public static function acl_instance($class_name)**
This method is used for auto-discovery of available resources. Since the resource ID, actions and conditions must be obtained from an object,
we need a way to get and instance of the object given only the class name. Not that the object returned shoul not be used for anything except calling `acl_*` methods
to discover resource properties.
Note that the `Model_AACL_Rule` itself extends `Sprig_AACL`. Instead of the default CRUD actions though it just specifies `grant` and `revoke` actions. This means you can
create rules about whether a role can itsef grant or revoke access! Note that the checking is not automatic though. That would prevent installers from creating rules or similar
due to not having a user logged in yet! It is still up to the developer to check the user has permission to grant or revoke using check().
`AACL_Resource` objects can define conditions which allow rules to provide fine-grained control. Since conditions are resource specific, only conditions defined by the resource
Specifies a specific action of that resource which may be accessed. For example if role is `m:post` and action is `delete`, access will be granted to delete any post object.
If the action is NULL or does not exist (i.e. is not returned by the resource's acl_actions() method) then access will be granted for any action on the resource.
If you grant a rule which is *more* permissive than one or more rules that currently exist, the current rules will be automatically deleted since they are now logically useless.
using `$reource->acl_actions(TRUE)`. If this returns a string action then that action will be used for checking without having to specify the `$action` parameter.
Note that the string resource ID can't be specified since the `check()` function requires access to the objects acl_* methods. It
is simpler not to have to define mappings from id back to class name in some separate global class in order to create instances.
If I think of a way to make this neat and relatively seemless I may implement it but I don't feel this is a big issue.
This does mean that currently there is no real way to check permisions on a controller resource other than the one in which the call to `AACL::check()` resides.
In practice this is unlikely to be a real limitiation.
Since a controller object knows the currently executing action, the current controller action can be checked simply with `AACL::check($this)`.
Since models don't inherently know which action is being requested, `$action` parameter must be specified otherwise the user will need to have access to ALL actions
Since controllers inherently know about the currently executing action, all actions in a controller will automatically be protected (according to their action-specific
rules) simply by calling `AACL::check($this)` in the controller's `before()` method.
A major motivation for this library is to make it easy to create Rules using a UI. To facilitate this, all potential resources defined in the application can be found using
`AACL::list_resources()`. This returns a multi-dimensional array listing all the resources and any actions or conditions they define.
It works by scanning the file system and using reflection so in a big app this is likely to take some time. I feel that is not a big deal here though as it should only ever be done in
admin control panels not in public parts of the app and it allows a very powerful system that doesn't require maintaining lenthly and complex mappings of classes and resources.
Note that `list_resources()` will only return the basic types in the case of models, not every possible model id. In other words you will get a single entry
for `m:post` rather than `m:post.1, m:post.2, ...`. It is left for the developer to retrieve this data if necessary for a UI.
A basic rule management UI will hopefully be added to the module at some point to help get started. It will naturally be disabled in all but 'developement' environment.