Access Control Lists (ACL)

Phalcon\Acl provides an easy and lightweight management of ACLs as well as the permissions attached to them. Access Control Lists (ACL) allow an application to control access to its areas and the underlying objects from requests. You are encouraged to read more about the ACL methodology so as to be familiar with its concepts.

In summary, ACLs have roles and resources. Resources are objects which abide by the permissions defined to them by the ACLs. Roles are objects that request access to resources and can be allowed or denied access by the ACL mechanism.

Creating an ACL

This component is designed to initially work in memory. This provides ease of use and speed in accessing every aspect of the list. The Phalcon\Acl constructor takes as its first parameter an adapter used to retrieve the information related to the control list. An example using the memory adapter is below:

  1. <?php
  3. use Phalcon\Acl\Adapter\Memory as AclList;
  5. $acl = new AclList();

By default Phalcon\Acl allows access to action on resources that have not yet been defined. To increase the security level of the access list we can define a deny level as a default access level.

  1. <?php
  3. use Phalcon\Acl;
  5. // Default action is deny access
  6. $acl->setDefaultAction(
  7.     Acl::DENY
  8. );

Adding Roles to the ACL

A role is an object that can or cannot access certain resources in the access list. As an example, we will define roles as groups of people in an organization. The Phalcon\Acl\Role class is available to create roles in a more structured way. Let’s add some roles to our recently created list:

  1. <?php
  3. use Phalcon\Acl\Role;
  5. // Create some roles.
  6. // The first parameter is the name, the second parameter is an optional description.
  7. $roleAdmins = new Role('Administrators', 'Super-User role');
  8. $roleGuests = new Role('Guests');
  10. // Add 'Guests' role to ACL
  11. $acl->addRole($roleGuests);
  13. // Add 'Designers' role to ACL without a Phalcon\Acl\Role
  14. $acl->addRole('Designers');

As you can see, roles are defined directly without using an instance.

Adding Resources

Resources are objects where access is controlled. Normally in MVC applications resources refer to controllers. Although this is not mandatory, the Phalcon\Acl\Resource class can be used in defining resources. It’s important to add related actions or operations to a resource so that the ACL can understand what it should to control.

  1. <?php
  3. use Phalcon\Acl\Resource;
  5. // Define the 'Customers' resource
  6. $customersResource = new Resource('Customers');
  8. // Add 'customers' resource with a couple of operations
  10. $acl->addResource(
  11.     $customersResource,
  12.     'search'
  13. );
  15. $acl->addResource(
  16.     $customersResource,
  17.     [
  18.         'create',
  19.         'update',
  20.     ]
  21. );

Defining Access Controls

Now that we have roles and resources, it’s time to define the ACL (i.e. which roles can access which resources). This part is very important especially taking into consideration your default access level allow or deny.

  1. <?php
  3. // Set access level for roles into resources
  5. $acl->allow('Guests', 'Customers', 'search');
  7. $acl->allow('Guests', 'Customers', 'create');
  9. $acl->deny('Guests', 'Customers', 'update');

The allow() method designates that a particular role has granted access to a particular resource. The deny() method does the opposite.

Querying an ACL

Once the list has been completely defined. We can query it to check if a role has a given permission or not.

  1. <?php
  3. // Check whether role has access to the operations
  5. // Returns 0
  6. $acl->isAllowed('Guests', 'Customers', 'edit');
  8. // Returns 1
  9. $acl->isAllowed('Guests', 'Customers', 'search');
  11. // Returns 1
  12. $acl->isAllowed('Guests', 'Customers', 'create');

Function based access

Also you can add as 4th parameter your custom function which must return boolean value. It will be called when you use isAllowed() method. You can pass parameters as associative array to isAllowed() method as 4th argument where key is parameter name in our defined function.

  1. <?php
  2. // Set access level for role into resources with custom function
  3. $acl->allow(
  4.     'Guests',
  5.     'Customers',
  6.     'search',
  7.     function ($a) {
  8.         return $a % 2 === 0;
  9.     }
  10. );
  12. // Check whether role has access to the operation with custom function
  14. // Returns true
  15. $acl->isAllowed(
  16.     'Guests',
  17.     'Customers',
  18.     'search',
  19.     [
  20.         'a' => 4,
  21.     ]
  22. );
  24. // Returns false
  25. $acl->isAllowed(
  26.     'Guests',
  27.     'Customers',
  28.     'search',
  29.     [
  30.         'a' => 3,
  31.     ]
  32. );

Also if you don’t provide any parameters in isAllowed() method then default behaviour will be Acl::ALLOW. You can change it by using method setNoArgumentsDefaultAction().

  1. <?php
  3. use Phalcon\Acl;
  5. // Set access level for role into resources with custom function
  6. $acl->allow(
  7.     'Guests',
  8.     'Customers',
  9.     'search',
  10.     function ($a) {
  11.         return $a % 2 === 0;
  12.     }
  13. );
  15. // Check whether role has access to the operation with custom function
  17. // Returns true
  18. $acl->isAllowed(
  19.     'Guests',
  20.     'Customers',
  21.     'search'
  22. );
  24. // Change no arguments default action
  25. $acl->setNoArgumentsDefaultAction(
  26.     Acl::DENY
  27. );
  29. // Returns false
  30. $acl->isAllowed(
  31.     'Guests',
  32.     'Customers',
  33.     'search'
  34. );

Objects as role name and resource name

You can pass objects as roleName and resourceName. Your classes must implement Phalcon\Acl\RoleAware for roleName and Phalcon\Acl\ResourceAware for resourceName.

Our UserRole class

  1. <?php
  3. use Phalcon\Acl\RoleAware;
  5. // Create our class which will be used as roleName
  6. class UserRole implements RoleAware
  7. {
  8.     protected $id;
  10.     protected $roleName;
  12.     public function __construct($id, $roleName)
  13.     {
  14.         $this->id       = $id;
  15.         $this->roleName = $roleName;
  16.     }
  18.     public function getId()
  19.     {
  20.         return $this->id;
  21.     }
  23.     // Implemented function from RoleAware Interface
  24.     public function getRoleName()
  25.     {
  26.         return $this->roleName;
  27.     }
  28. }

And our ModelResource class

  1. <?php
  3. use Phalcon\Acl\ResourceAware;
  5. // Create our class which will be used as resourceName
  6. class ModelResource implements ResourceAware
  7. {
  8.     protected $id;
  10.     protected $resourceName;
  12.     protected $userId;
  14.     public function __construct($id, $resourceName, $userId)
  15.     {
  16.         $this->id           = $id;
  17.         $this->resourceName = $resourceName;
  18.         $this->userId       = $userId;
  19.     }
  21.     public function getId()
  22.     {
  23.         return $this->id;
  24.     }
  26.     public function getUserId()
  27.     {
  28.         return $this->userId;
  29.     }
  31.     // Implemented function from ResourceAware Interface
  32.     public function getResourceName()
  33.     {
  34.         return $this->resourceName;
  35.     }
  36. }

Then you can use them in isAllowed() method.

  1. <?php
  3. use UserRole;
  4. use ModelResource;
  6. // Set access level for role into resources
  7. $acl->allow('Guests', 'Customers', 'search');
  8. $acl->allow('Guests', 'Customers', 'create');
  9. $acl->deny('Guests', 'Customers', 'update');
  11. // Create our objects providing roleName and resourceName
  13. $customer = new ModelResource(
  14.     1,
  15.     'Customers',
  16.     2
  17. );
  19. $designer = new UserRole(
  20.     1,
  21.     'Designers'
  22. );
  24. $guest = new UserRole(
  25.     2,
  26.     'Guests'
  27. );
  29. $anotherGuest = new UserRole(
  30.     3,
  31.     'Guests'
  32. );
  34. // Check whether our user objects have access to the operation on model object
  36. // Returns false
  37. $acl->isAllowed(
  38.     $designer,
  39.     $customer,
  40.     'search'
  41. );
  43. // Returns true
  44. $acl->isAllowed(
  45.     $guest,
  46.     $customer,
  47.     'search'
  48. );
  50. // Returns true
  51. $acl->isAllowed(
  52.     $anotherGuest,
  53.     $customer,
  54.     'search'
  55. );

Also you can access those objects in your custom function in allow() or deny(). They are automatically bind to parameters by type in function.

  1. <?php
  3. use UserRole;
  4. use ModelResource;
  6. // Set access level for role into resources with custom function
  7. $acl->allow(
  8.     'Guests',
  9.     'Customers',
  10.     'search',
  11.     function (UserRole $user, ModelResource $model) { // User and Model classes are necessary
  12.         return $user->getId == $model->getUserId();
  13.     }
  14. );
  16. $acl->allow(
  17.     'Guests',
  18.     'Customers',
  19.     'create'
  20. );
  22. $acl->deny(
  23.     'Guests',
  24.     'Customers',
  25.     'update'
  26. );
  28. // Create our objects providing roleName and resourceName
  30. $customer = new ModelResource(
  31.     1,
  32.     'Customers',
  33.     2
  34. );
  36. $designer = new UserRole(
  37.     1,
  38.     'Designers'
  39. );
  41. $guest = new UserRole(
  42.     2,
  43.     'Guests'
  44. );
  46. $anotherGuest = new UserRole(
  47.     3,
  48.     'Guests'
  49. );
  51. // Check whether our user objects have access to the operation on model object
  53. // Returns false
  54. $acl->isAllowed(
  55.     $designer,
  56.     $customer,
  57.     'search'
  58. );
  60. // Returns true
  61. $acl->isAllowed(
  62.     $guest,
  63.     $customer,
  64.     'search'
  65. );
  67. // Returns false
  68. $acl->isAllowed(
  69.     $anotherGuest,
  70.     $customer,
  71.     'search'
  72. );

You can still add any custom parameters to function and pass associative array in isAllowed() method. Also order doesn’t matter.

Roles Inheritance

You can build complex role structures using the inheritance that Phalcon\Acl\Role provides. Roles can inherit from other roles, thus allowing access to supersets or subsets of resources. To use role inheritance, you need to pass the inherited role as the second parameter of the method call, when adding that role in the list.

  1. <?php
  3. use Phalcon\Acl\Role;
  5. // ...
  7. // Create some roles
  9. $roleAdmins = new Role('Administrators', 'Super-User role');
  11. $roleGuests = new Role('Guests');
  13. // Add 'Guests' role to ACL
  14. $acl->addRole($roleGuests);
  16. // Add 'Administrators' role inheriting from 'Guests' its accesses
  17. $acl->addRole($roleAdmins, $roleGuests);

Setup relationships after adding roles

Or you may prefer to add all of your roles together and then define the inheritance relationships afterwards.

  1. <?php
  3. use Phalcon\Acl\Role;
  5. // Create some roles
  6. $roleAdmins = new Role('Administrators', 'Super-User role');
  7. $roleGuests = new Role('Guests');
  9. // Add Roles to ACL
  10. $acl->addRole($roleGuests);
  11. $acl->addRole($roleAdmins);
  13. // Have 'Administrators' role inherit from 'Guests' its accesses
  14. $acl->addInherit($roleAdmins, $roleGuests);

Serializing ACL lists

To improve performance Phalcon\Acl instances can be serialized and stored in APC, session, text files or a database table so that they can be loaded at will without having to redefine the whole list. You can do that as follows:

  1. <?php
  3. use Phalcon\Acl\Adapter\Memory as AclList;
  5. // ...
  7. // Check whether ACL data already exist
  8. if (!is_file('app/security/acl.data')) {
  9.     $acl = new AclList();
  11.     // ... Define roles, resources, access, etc
  13.     // Store serialized list into plain file
  14.     file_put_contents(
  15.         'app/security/acl.data',
  16.         serialize($acl)
  17.     );
  18. } else {
  19.     // Restore ACL object from serialized file
  20.     $acl = unserialize(
  21.         file_get_contents('app/security/acl.data')
  22.     );
  23. }
  25. // Use ACL list as needed
  26. if ($acl->isAllowed('Guests', 'Customers', 'edit')) {
  27.     echo 'Access granted!';
  28. } else {
  29.     echo 'Access denied :(';
  30. }

It’s recommended to use the Memory adapter during development and use one of the other adapters in production.

Events

Phalcon\Acl is able to send events to an EventsManager if it’s present. Events are triggered using the type ‘acl’. Some events when returning boolean false could stop the active operation. The following events are supported:

Event NameTriggeredCan stop operation?
beforeCheckAccessTriggered before checking if a role/resource has accessYes
afterCheckAccessTriggered after checking if a role/resource has accessNo

The following example demonstrates how to attach listeners to this component:

  1. <?php
  3. use Phalcon\Acl\Adapter\Memory as AclList;
  4. use Phalcon\Events\Event;
  5. use Phalcon\Events\Manager as EventsManager;
  7. // ...
  9. // Create an event manager
  10. $eventsManager = new EventsManager();
  12. // Attach a listener for type 'acl'
  13. $eventsManager->attach(
  14.     'acl:beforeCheckAccess',
  15.     function (Event $event, $acl) {
  16.         echo $acl->getActiveRole();
  18.         echo $acl->getActiveResource();
  20.         echo $acl->getActiveAccess();
  21.     }
  22. );
  24. $acl = new AclList();
  26. // Setup the $acl
  27. // ...
  29. // Bind the eventsManager to the ACL component
  30. $acl->setEventsManager($eventsManager);

Implementing your own adapters

The Phalcon\Acl\AdapterInterface interface must be implemented in order to create your own ACL adapters or extend the existing ones.