Access Control Lists (ACL)

    Phalcon\Acl provides an easy and lightweight management of ACLs as well as the permissions attached to them. (ACL) allow an application to control access to its areas and the underlying objects from requests.

    In short, ACLs have two objects: The object that needs access, and the object that we need access to. In the programming world, these are usually referred to as Roles and Components. In the Phalcon world, we use the terminology Role and .

    As seen above in the use case, an Role is defined as who needs to access a particular i.e. an area of the application. A Component is defined as the area of the application that needs to be accessed.

    Using the component, we can tie those two together, and strengthen the security of our application, allowing only specific roles to be bound to specific components.

    Creating an ACL

    uses adapters to store and work with roles and components. The only adapter available right now is Phalcon\Acl\Adapter\Memory. Having the adapter use the memory, significantly increases the speed that the ACL is accessed but also comes with drawbacks. The main drawback is that memory is not persistent, so the developer will need to implement a storing strategy for the ACL data, so that the ACL is not generated at every request. This could easily lead to delays and unnecessary processing, especially if the ACL is quite big and/or stored in a database or file system.

    Phalcon also offers an easy way for developers to build their own adapters by implementing the interface.

    The Phalcon\Acl constructor takes as its first parameter an adapter used to retrieve the information related to the control list.

    There are two self explanatory actions that the provides:

    • Phalcon\Acl\Enum::DENYThe default action is Phalcon\Acl\Enum::DENY for any Role or . This is on purpose to ensure that only the developer or application allows access to specific components and not the ACL component itself.
    1. <?php
    3. use Phalcon\Acl\Enum;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    6. $acl = new AclList();
    8. $acl->setDefaultAction(Enum::ALLOW);

    Adding Roles

    As mentioned above, a is an object that can or cannot access a set of Component in the access list.

    There are two ways of adding roles to our list.

    • by using a object or
    • using a string, representing the name of the roleTo see this in action, using the example outlined above, we will add the relevant Phalcon\Acl\Role objects in our list.

    Role objects. The first parameter is the name of the role, the second the description

    1. <?php
    3. use Phalcon\Acl\Adapter\Memory as AclList;
    4. use Phalcon\Acl\Role;
    6. $acl = new AclList();
    8. $roleAdmins     = new Role('admins', 'Administrator Access');
    9. $roleAccounting = new Role('accounting', 'Accounting Department Access'); 
    11. $acl->addRole($roleAdmins);
    12. $acl->addRole($roleAccounting);

    Strings. Add the role with just the name directly to the ACL:

    1. <?php
    3. use Phalcon\Acl\Adapter\Memory as AclList;
    5. $acl = new AclList();
    7. $acl->addRole('manager');
    8. $acl->addRole('guest');

    Adding Components

    There are two ways of adding components to our list.

    • by using a Phalcon\Acl\Component object or
    • using a string, representing the name of the roleSimilar to the addRole, addComponent requires a name for the component and an optional description.

    Component objects. The first parameter is the name of the component, the second the description

    1. <?php
    3. use Phalcon\Acl\Adapter\Memory as AclList;
    4. use Phalcon\Acl\Component;
    6. $acl = new AclList();
    8. $admin   = new Component('admin', 'Administration Pages');
    9. $reports = new Component('reports', 'Reports Pages');
    11. $acl->addComponent(
    12.     $admin,
    13.     [
    14.         'dashboard',
    15.         'users',
    16.     ]
    17. );
    19. $acl->addComponent(
    20.     $reports,
    21.     [
    22.         'list',
    23.         'add',
    24.     ]
    25. );

    Strings. Add the component with just the name directly to the ACL:

    1. <?php
    3. use Phalcon\Acl\Adapter\Memory as AclList;
    5. $acl = new AclList();
    7. $acl->addComponent(
    8.     'admin',
    9.     [
    10.         'dashboard',
    11.         'users',
    12.     ]
    13. );
    15. $acl->addComponent(
    16.     'reports',
    17.     [
    18.         'list',
    19.         'add',
    20.     ]
    21. );

    After both the Roles and Components have been defined, we need to tie them together so that the access list can be created. This is the most important step in the role since a small mistake here can allow access to roles for components that the developer does not intend to. As mentioned earlier, the default access action for is Phalcon\Acl\Enum::DENY, following the whitelist approach.

    To tie Roles and Components together we use the allow() and deny() methods exposed by the class.

    1. <?php
    3. use Phalcon\Acl\Adapter\Memory as AclList;
    4. use Phalcon\Acl\Role;
    5. use Phalcon\Acl\Component;
    7. $acl = new AclList();
    9. /**
    10.  * Add the roles
    11.  */
    12. $acl->addRole('manager');
    13. $acl->addRole('accounting');
    14. $acl->addRole('guest');
    17. /**
    18.  * Add the Components
    19.  */
    21. $acl->addComponent(
    22.     'admin',
    23.     [
    24.         'dashboard',
    25.         'users',
    26.         'view',
    27.     ]
    28. );
    30. $acl->addComponent(
    31.     'reports',
    32.     [
    33.         'list',
    34.         'add',
    35.         'view',
    36.     ]
    37. );
    39. $acl->addComponent(
    40.     'session',
    41.     [
    42.         'login',
    43.         'logout',
    44.     ]
    45. );
    47. /**
    48.  * Now tie them all together 
    49.  */
    50. $acl->allow('manager', 'admin', 'users');
    51. $acl->allow('manager', 'reports', ['list', 'add']);
    52. $acl->allow('*', 'session', '*');
    53. $acl->allow('*', '*', 'view');
    55. $acl->deny('guest', '*', 'view');

    What the above lines tell us:

    1. $acl->allow('manager', 'admin', 'users');

    For the manager role, allow access to the admin component and users action. To bring this into perspective with a MVC application, the above line says that the group manager is allowed to access the admin controller and users action.

    You can also pass an array as the action parameter when invoking the allow() command. The above means that for the manager role, allow access to the reports component and list and add actions. Again to bring this into perspective with a MVC application, the above line says that the group manager is allowed to access the reports controller and list and add actions.

    1. $acl->allow('*', 'session', '*');

    Wildcards can also be used to do mass matching for roles, components or actions. In the above example, we allow every role to access every action in the session component. This command will give access to the manager, accounting and guest roles, access to the session component and to the login and logout actions.

    1. $acl->allow('*', '*', 'view');

    Similarly the above gives access to any role, any component that has the view action. In a MVC application, the above is the equivalent of allowing any group to access any controller that exposes a viewAction.

    1. $acl->deny('guest', '*', 'view');

    For the guest role, we deny access to all components with the view action. Despite the fact that the default access level is Acl\Enum::DENY in our example above, we specifically allowed the view action to all roles and components. This includes the guest role. We want to allow the guest role access only to the session component and the login and logout actions, since guests are not logged into our application.

    1. $acl->allow('*', '*', 'view');

    This gives access to the view access to everyone, but we want the guest role to be excluded from that so the following line does what we need.

    Querying

    Once the list has been defined, we can query it to check if a particular role has access to a particular component and action. To do so, we need to use the isAllowed() method.

    1. <?php
    3. use Phalcon\Acl;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    5. use Phalcon\Acl\Role;
    6. use Phalcon\Acl\Component;
    7. $acl = new AclList();
    9. /**
    10.  * Setup the ACL
    11.  */
    12. $acl->addRole('manager');
    13. $acl->addRole('accounting');
    14. $acl->addRole('guest');
    16. $acl->addComponent(
    17.     'admin',
    18.     [
    19.         'dashboard',
    20.         'users',
    21.         'view',
    22.     ]
    23. );
    25. $acl->addComponent(
    26.     'reports',
    27.     [
    28.         'list',
    29.         'add',
    30.         'view',
    31.     ]
    32. );
    34. $acl->addComponent(
    35.     'session',
    36.     [
    37.         'login',
    38.         'logout',
    39.     ]
    40. );
    42. $acl->allow('manager', 'admin', 'users');
    43. $acl->allow('manager', 'reports', ['list', 'add']);
    44. $acl->allow('*', 'session', '*');
    45. $acl->allow('*', '*', 'view');
    47. $acl->deny('guest', '*', 'view');
    49. // ....
    53. // true - defined explicitly
    54. $acl->isAllowed('manager', 'admin', 'dashboard');
    56. // true - defined with wildcard
    57. $acl->isAllowed('manager', 'session', 'login');
    59. // true - defined with wildcard
    60. $acl->isAllowed('accounting', 'reports', 'view');
    62. // false - defined explicitly
    63. $acl->isAllowed('guest', 'reports', 'view');
    65. // false - default access level
    66. $acl->isAllowed('guest', 'reports', 'add');

    Function based access

    Depending on the needs of your application, you might need another layer of calculations to allow or deny access to users through the ACL. The method isAllowed() accepts a 4th parameter which is a callable such as an anonymous function.

    1. <?php
    3. use Phalcon\Acl;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    5. use Phalcon\Acl\Role;
    6. use Phalcon\Acl\Component;
    8. $acl = new AclList();
    10. /**
    11.  * Setup the ACL
    12.  */
    13. $acl->addRole('manager');
    15. $acl->addComponent(
    16.     'admin',
    17.     [
    18.         'dashboard',
    19.         'users',
    20.         'view',
    21.     ]
    22. );
    24. // Set access level for role into components with custom function
    25. $acl->allow(
    26.     'manager',
    27.     'admin',
    28.     'dashboard',
    29.     function ($name) {
    30.         return boolval('Bob' !== $name);
    31.     }
    32. );

    Now that the callable is defined in the ACL, we will need to call the isAllowed() method with an array as the fourth parameter:

    You can also omit to pass the fourth parameter to isAllowed() if you wish. The default action for a call to isAllowed() without the last parameter is Acl\Enum::DENY. To change this behavior, you can make a call to setNoArgumentsDefaultAction():

    1. <?php
    3. use Phalcon\Acl;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    5. use Phalcon\Acl\Role;
    6. use Phalcon\Acl\Component;
    8. $acl = new AclList();
    10. /**
    11.  * Setup the ACL
    12.  */
    13. $acl->addRole('manager');
    15. $acl->addComponent(
    16.     'admin',
    17.     [
    18.         'dashboard',
    19.         'users',
    20.         'view',
    21.     ]
    22. );
    24. // Set access level for role into components with custom function
    25. $acl->allow(
    26.     'manager',
    27.     'admin',
    28.     'dashboard',
    29.     function ($name) {
    30.         return boolval('Bob' !== $name);
    31.     }
    32. );
    34. // Returns false
    35. $acl->isAllowed('manager', 'admin', 'dashboard');
    37. $acl->setNoArgumentsDefaultAction(
    38.     Acl\Enum::ALLOW
    39. );
    41. // Returns true
    42. $acl->isAllowed('manager', 'admin', 'dashboard');

    Objects as role name and component name

    Phalcon allows developers to define their own role and component objects. These objects must implement the supplied interfaces:

    We can implement the in our custom class with its own logic. The example below shows a new role object called ManagerRole:

    1. <?php
    3. use Phalcon\Acl\RoleAware;
    5. // Create our class which will be used as roleName
    6. class ManagerRole 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. }

    We can implement the Phalcon\Acl\ComponentAware in our custom class with its own logic. The example below shows a new role object called ReportsComponent:

    1. <?php
    3. use Phalcon\Acl\ComponentAware;
    5. // Create our class which will be used as componentName
    6. class ReportsComponent implements ComponentAware
    7. {
    9.     protected $componentName;
    11.     protected $userId;
    13.     public function __construct($id, $componentName, $userId)
    14.     {
    15.         $this->id            = $id;
    16.         $this->componentName = $componentName;
    17.         $this->userId        = $userId;
    18.     }
    20.     public function getId()
    21.     {
    22.         return $this->id;
    23.     }
    25.     public function getUserId()
    26.     {
    27.         return $this->userId;
    28.     }
    30.     // Implemented function from ComponentAware Interface
    31.     public function getComponentName()
    32.     {
    33.         return $this->componentName;
    34.     }
    35. }

    These objects can now be used in our ACL.

    1. <?php
    3. use ManagerRole;
    4. use Phalcon\Acl;
    5. use Phalcon\Acl\Adapter\Memory as AclList;
    6. use Phalcon\Acl\Role;
    7. use Phalcon\Acl\Component;
    8. use ReportsComponent;
    10. $acl = new AclList();
    12. /**
    13.  * Add the roles
    14.  */
    15. $acl->addRole('manager');
    17. /**
    18.  * Add the Components
    19.  */
    20. $acl->addComponent(
    21.     'reports',
    22.     [
    23.         'list',
    24.         'add',
    25.         'view',
    26.     ]
    27. );
    29. /**
    30.  * Now tie them all together with a custom function. The ManagerRole and
    31.  * ModelSbject parameters are necessary for the custom function to work 
    32.  */
    33. $acl->allow(
    34.     'manager', 
    35.     'reports', 
    36.     'list',
    37.     function (ManagerRole $manager, ModelComponent $model) {
    38.         return boolval($manager->getId() === $model->getUserId());
    39.     }
    40. );
    42. // Create the custom objects
    43. $levelOne = new ManagerRole(1, 'manager-1');
    44. $levelTwo = new ManagerRole(2, 'manager');
    45. $admin    = new ManagerRole(3, 'manager');
    47. // id - name - userId
    48. $reports  = new ModelComponent(2, 'reports', 2);
    50. // Check whether our user objects have access 
    51. // Returns false
    52. $acl->isAllowed($levelOne, $reports, 'list');
    54. // Returns true
    55. $acl->isAllowed($levelTwo, $reports, 'list');
    57. // Returns false
    58. $acl->isAllowed($admin, $reports, 'list');

    The second call for $levelTwo evaluates true since the getUserId() returns 2 which in turn is evaluated in our custom function. Also note that in the custom function for allow() the objects are automatically bound, providing all the data necessary for the custom function to work. The custom function can accept any number of additional parameters. The order of the parameters defined in the function() constructor does not matter, because the objects will be automatically discovered and bound.

    To remove duplication and increase efficiency in your application, the ACL offers inheritance in roles. This means that you can define one as a base and after that inherit from it offering access to supersets or subsets of components. To use role inheritance, you need, 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;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    5. use Phalcon\Acl\Role;
    7. $acl = new AclList();
    9. /**
    10.  * Create the roles
    11.  */
    12. $manager    = new Role('Managers');
    13. $accounting = new Role('Accounting Department');
    14. $guest      = new Role('Guests');
    16. /**
    17.  * Add the `guest` role to the ACL 
    18.  */
    19. $acl->addRole($guest);
    21. /**
    22.  * Add the `accounting` inheriting from `guest` 
    23.  */
    24. $acl->addRole($accounting, $guest);
    26. /**
    27.  * Add the `manager` inheriting from `accounting` 
    28.  */
    29. $acl->addRole($manager, $accounting);

    Whatever access guests have will be propagated to accounting and in turn accounting will be propagated to manager

    Based on the application design, you might prefer to add first all the roles and then define the relationship between them.

    1. <?php
    3. use Phalcon\Acl;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    5. use Phalcon\Acl\Role;
    7. $acl = new AclList();
    9. /**
    10.  * Create the roles
    11.  */
    12. $manager    = new Role('Managers');
    13. $accounting = new Role('Accounting Department');
    14. $guest      = new Role('Guests');
    16. /**
    17.  * Add all the roles
    18.  */
    19. $acl->addRole($manager);
    20. $acl->addRole($accounting);
    21. $acl->addRole($guest);
    23. /**
    24.  * Add the inheritance 
    25.  */
    26. $acl->addInherit($manager, $accounting);
    27. $acl->addInherit($accounting, $guest);

    Serializing ACL lists

    can be serialized and stored in a cache system to improve efficiency. You can store the serialized object in APC, session, file system, database, Redis etc. This way you can retrieve the ACL quickly without having to read the underlying data that create the ACL nor will you have to compute the ACL in every request.

    1. <?php
    3. use Phalcon\Acl;
    4. use Phalcon\Acl\Adapter\Memory as AclList;
    6. $aclFile = 'app/security/acl.cache';
    7. // Check whether ACL data already exist
    8. if (true !== is_file($aclFile)) {
    10.     // The ACL does not exist - build it
    11.     $acl = new AclList();
    13.     // ... Define roles, components, access, etc
    15.     // Store serialized list into plain file
    16.     file_put_contents(
    17.         $aclFile,
    18.         serialize($acl)
    19.     );
    20. } else {
    21.     // Restore ACL object from serialized file
    22.     $acl = unserialize(
    23.         file_get_contents($aclFile)
    24.     );
    25. }
    27. // Use ACL list as needed
    28. if (true === $acl->isAllowed('manager', 'admin', 'dashboard')) {
    29.     echo 'Access granted!';
    30. } else {
    31. }

    It is a good practice to not use serialization of the ACL during development, to ensure that your ACL is built in every request, while other adapters or means of serializing and storing the ACL in production.

    Events

    can work in conjunction with the EventsManager if present, to fire events to your application. Events are triggered using the type acl. Events that return false can stop the active role. The following events are available:

    The following example demonstrates how to attach listeners to the ACL:

    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.