Recommend this page to a friend! |
Download |
Info | Documentation | Files | Install with Composer | Download | Reputation | Support forum | Blog | Links |
Ratings | Unique User Downloads | Download Rankings | ||||
70% | Total: 456 | All time: 6,119 This week: 41 |
Version | License | PHP version | Categories | |||
acl 1.0.5 | MIT/X Consortium ... | 7 | User Management, PHP 7 |
Collaborate with this project | Authors Samshal Contributor | |
Acl - github.com Description This class can manage permission access control lists. |
Samshal\Acl adds a role based permission system for user authentication. In general, it provides a lightweight access control list for privileges and permission management.
Access Control Lists allow an application to control access to its areas, they provide a flexible interface for creating Permissions, Roles, Resources and assigning the created permissions on roles.
This component is an implementation of an ACL, it makes it easy for you to get up and running with user authorization.
Resources are objects which acts in accordance to the permissions defined on them by the ACLs. Roles are objects that requests access to resources and can be allowed or denied by the ACL layers. Permissions are just rules defined on Resources.
This software is distributed under the MIT license. Please read LICENSE for information on the software availability and distribution.
Samshal\Acl is available via Composer/Packagist, so just add this line to your composer.json
file:
{
"require":{
"samshal/acl":"^2.0"
}
}
or
composer require samshal/acl
Creating an ACL component is as easy as instantiating Samshal\Acl
. The constructor __currently__ accepts no arguments. An example of instantiation is:
<?php
require "vendor/autoload.php";
use Samshal\Acl;
use Samshal\Acl\{
Role\DefaultRole as Role,
Resource\DefaultResource as Resource,
Permission\DefaultPermission as Permission
};
$acl = new Acl();
The ACL provides an add
method for adding new objects generically. In other words, to add a new role to the Acl, just pass in a Role Object
to the ACLs
add` method. You can also do the same for Resources and Permissions.
A Role Object is an instance of the \Samshal\Acl\Role\DefaultRole
object or more generally, an object that implements the \Samshal\Acl\Role\RoleInterface
and \Samshal\Acl\ObjectInterface
contracts. It accepts the name of the Role to create as parameter and the description for the created role as optional second parameter.
Similarly Resource objects are instances of the \Samshal\Acl\Resource\DefaultResource
object which also implements the \Samshal\Acl\Resource\ResourceInterface
and \Samshal\Acl\ObjectInterface
interfaces, Likewise for permissions, they must implement the \Samshal\Acl\Permission\PermissionInterface
and the \Samshal\Acl\ObjectInterface
contracts or be new instances of the \Samshal\Acl\Permission\DefaultPermission
class.
Generally, Roles, Resources and Permissions are referred to as Objects. They must all implement the \Samshal\Acl\ObjectInterface
contract.
...
$adminRole = new Role("Admin");
$accountantRole = new Role("Accountant", "This is optional: anybody who`s not an admin is an accountant");
$acl->add($adminRole);
$acl->add($accountantRole);
$patientFinancialHistoryResource = new Resource("patientFinancialHistory");
$acl->add($patientFinancialHistoryResource);
$editPermission = new Permission("edit");
$viewPermission = new Permission("view");
$acl->add($editPermission, $viewPermission);
...
Internally, the created objects are stored in Registries which are fully serializable. This makes it easy to transfer/get the objects from anywhere; a persistent storage, a database and anywhere else data can be stored/received. More on this later.
Samshal\Acl provides a more intuitive way to create objects. Instead of creating new objects everytime you need to add them to the registry, why not call a single method that can determine which kind of object you are trying to create and have it do it automatically? The ACL provides an addRole
, addResource
and addPermission
methods for this purpose which all accepts string values as parameters.
Example:
...
$acl->addRole('Admin');
$acl->addRole('Accountant');
$acl->addResource('patientFinancialHistory');
$acl->addPermission('edit');
$acl->addPermission('view');
...
Cool right? The add methods (addRole, addResource, addPermission and add) are variadic, they can accept an unlimited number of arguments at a time. So we could even make our lives less more boring by doing this while adding the Roles
...
$acl->addRole('Admin', 'Accountant');
...
or this for the Permissions.
...
$acl->addPermission('edit', 'view', 'create', 'print', 'delete'); //you can add even more permissions!
...
The reason why this component exists is to set permissions on resources and grant/deny these permissions to roles. The snippet below gives an example of how to set these permissions.
...
/
* In the example below, admin is the name of a Role that's been added to the ACl using add() or addRole().
* Similarly view is a permission and patientFinancialHistory is a resource.
*
* Use the `can` keyword in between a role and a permission in a chain to set make the resource in question accessible or not to the role.
*/
$acl->admin->can->view('patientFinancialHistory');
$acl->accountant->cannot->delete('patientFinancialHistory'); //denying the role Accountant delete right on the PatienFinancialHistory resource.
...
To check the permission a role has on a certain resource, you can use a snippet similar to the following:
...
$booleanResultIndicatingPermission = $acl->can->admin->view('patientFinancialHistory');
//We are asking a very simple question: can an Admin role View the patientFinancialHistory resource?
//even better, we could use it in a conditional
if ($acl->can->accountant->delete('patientFinancialHistory'))
{
//delete the patients financial history!
}
else
{
//this user does not have any permission to delete this resource, let him know that
}
...
\Samshal\Acl
stores objects including the permissions on objects in registries which are fully serializable. This means you can convert your entire acl into a string and store that in a database or session and make it exist infinitely until you are ready to destroy it or __never use it again__.
...
$serializedAcl = serialize($acl);
//store $serializedAcl in a session
session_start();
$_SESSION["acl"] = $serializedAcl.
//or in a db
$sqlQuery = "INSERT INTO my_tbl VALUES ('$serializedAcl')";
/
* File Name: patientHistories.php
*/
session_start();
$acl = unserialize($_SESSION["acl"]);
//use it!
if ($acl->can->accountant->delete('patientFinanicalHistory'))
{
//delete the patients financial history!
}
else
{
//this user does not have any permission to delete this resource, let him know that
}
...
\Samshal\acl
allows roles to inherit permissions from other roles. The Acl component has an inherits
method that accepts a Role object as parameter. You can also pass in a string, but it must be the id of an already existent role object.
You can also call a Permission object without any parameter. This grants the permission in question on all resources defined within the ACL on the Role in session.
This library is currently developed and maintained by Samuel Adeshina
Road Map draft in progress.
Support follows PSR-2 PHP coding standards.
Please report any issue you find in the issues page. Pull requests are welcome.
Files (20) |
File | Role | Description | ||
---|---|---|---|---|
src (3 files, 4 directories) | ||||
tests (2 directories) | ||||
.gitignore | Data | Auxiliary data | ||
.travis.yml | Data | Auxiliary data | ||
composer.json | Data | Auxiliary data | ||
LICENSE | Lic. | License | ||
phpmetric_maintainability.png | Icon | Icon image | ||
README.md | Doc. | Documentation |
Files (20) | / | src |
File | Role | Description | ||
---|---|---|---|---|
Permission (2 files) | ||||
Registry (3 files) | ||||
Resource (2 files) | ||||
Role (2 files) | ||||
Acl.php | Class | Class source | ||
AclInterface.php | Class | Class source | ||
ObjectInterface.php | Class | Class source |
Files (20) | / | src | / | Permission |
File | Role | Description |
---|---|---|
DefaultPermission.php | Class | Class source |
PermissionInterface.php | Class | Class source |
Files (20) | / | src | / | Registry |
File | Role | Description |
---|---|---|
GlobalRegistry.php | Class | Class source |
Registry.php | Class | Class source |
RegistryInterface.php | Class | Class source |
Files (20) | / | src | / | Resource |
File | Role | Description |
---|---|---|
DefaultResource.php | Class | Class source |
ResourceInterface.php | Class | Class source |
Files (20) | / | src | / | Role |
File | Role | Description |
---|---|---|
DefaultRole.php | Class | Class source |
RoleInterface.php | Class | Class source |
The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page. |
Install with Composer |
Version Control | Unique User Downloads | Download Rankings | |||||||||||||||
100% |
|
|
User Ratings | ||||||||||||||||||||||||||||||
|
Applications that use this package |
If you know an application of this package, send a message to the author to add a link here.