访问控制列表 ACL（Access Control Lists ACL）

Phalcon在权限方面通过 Phalcon\Acl 提供了一个轻量级的 ACL(访问控制列表). Access Control Lists (ACL) 允许系统对用户的访问权限进行控制，比如允许访问某些资源而不允许访问其它资源等。 这里我们建议开发者了解一些关于ACL的技术。

ACL有两部分组成即角色和资源。 资源即是ACL定义的权限所依附的对象。 角色即是ACL所字义的请求者的身份，ACL决定了角色对资源的访问权限，允许访问或拒绝访问。

创建 ACL（Creating an ACL）

这个组件起先是设计工作在内存中的， 这样做提供了更高的访问速度。 Phalcon\Acl 构造器的第一个参数用于设置取得ACL的方式。 下面是使用内存适配器的例子：

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

默认情况下 Phalcon\Acl 允许我们访问未定义的资源中的action，为了提高安全性， 我们设置默认访问级别为‘拒绝’。

  1. <?php
  3. use Phalcon\Acl;
  5. // 设置默认访问级别为拒绝
  6. $acl->setDefaultAction(
  7.     Acl::DENY
  8. );

添加角色（Adding Roles to the ACL）

角色即是权限的集合体，其中定义了我们对资源的访问权限。 例如， 我们会把一个组织内的不同的人定义为不同的角色。 The Phalcon\Acl\Role 类使用一种更有组织的方式来定义角色。 这里我们创建一些角色：

  1. <?php
  3. use Phalcon\Acl\Role;
  5. // 创建角色
  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. // 添加 "Guests" 角色到ACL
  11. $acl->addRole($roleGuests);
  13. // 添加"Designers"到ACL, 仅使用此字符串。
  14. $acl->addRole("Designers");

上面我们看到，我们可以直接使用字符串来定义角色。

添加资源（Adding Resources）

资源即是访问控制要控制的对象之一。 正常情况下在mvc中资源一般是控制器。 Phalcon中我们使用 Phalcon\Acl\Resource 来定义资源。 非常重要的一点即是我们把相关的action或操作添加到资源中这样ACL才知道控制什么资源。

  1. <?php
  3. use Phalcon\Acl\Resource;
  5. // 定义 "Customers" 资源
  6. $customersResource = new Resource("Customers");
  8. // 为 "customers"资源添加一组操作
  10. $acl->addResource(
  11.     $customersResource,
  12.     "search"
  13. );
  15. $acl->addResource(
  16.     $customersResource,
  17.     [
  18.         "create",
  19.         "update",
  20.     ]
  21. );

定义访问控制（Defining Access Controls）

至此我们定义了角色及资源， 现在是定义ACL的时候了，即是定义角色对资源的访问。 这个部分是极其重要的，特别是在我们设定了默认的访问级别后。

  1. <?php
  3. // 设置角色对资源的访问级别
  4. $acl->allow("Guests", "Customers", "search");
  6. $acl->allow("Guests", "Customers", "create");
  8. $acl->deny("Guests", "Customers", "update");

allow()方法指定了允许角色对资源的访问， deny()方法则反之。

查询 ACL（Querying an ACL）

一旦访问控制表定义之后， 我们就可以通过它来检查角色是否有访问权限了。

  1. <?php
  3. // 查询角色是否有访问权限
  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. use Phalcon\Acl;
  3. <?php
  4. // Set access level for role into resources with custom function
  5. $acl->allow(
  6.     "Guests",
  7.     "Customers",
  8.     "search",
  9.     function ($a) {
  10.         return $a % 2 === 0;
  11.     }
  12. );
  14. // Check whether role has access to the operation with custom function
  16. // Returns true
  17. $acl->isAllowed(
  18.     "Guests",
  19.     "Customers",
  20.     "search"
  21. );
  23. // Change no arguments default action
  24. $acl->setNoArgumentsDefaultAction(
  25.     Acl::DENY
  26. );
  28. // Returns false
  29. $acl->isAllowed(
  30.     "Guests",
  31.     "Customers",
  32.     "search"
  33. );

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）

我们可以使用 Phalcon\Acl\Role 提供的继承机制来构造更复杂的角色。 Phalcon中的角色可以继承来自其它角色的 权限, 这样就可以实现更巧妙的资源访问控制。 如果要继承权限用户， 我们需要在添加角色函数的第二个参数中写上要继承的那个角色实例。

  1. <?php
  3. use Phalcon\Acl\Role;
  5. // ...
  7. // 创建角色
  9. $roleAdmins = new Role("Administrators", "Super-User role");
  11. $roleGuests = new Role("Guests");
  13. // 添加 "Guests" 到 ACL
  14. $acl->addRole($roleGuests);
  16. // 使Administrators继承Guests的访问权限
  17. $acl->addRole($roleAdmins, $roleGuests);

序列化 ACL 列表（Serializing ACL lists）

为了提高性能， Phalcon\Acl 的实例可以被实例化到APC, session， 文本或数据库中， 这样开发者就不需要重复的 定义acl了。 下面展示了如何去做：

  1. <?php
  3. use Phalcon\Acl\Adapter\Memory as AclList;
  5. // ...
  7. // 检查ACL数据是否存在
  8. if (!is_file("app/security/acl.data")) {
  9.     $acl = new AclList();
  11.     // ... Define roles, resources, access, etc
  13.     // 保存实例化的数据到文本文件中
  14.     file_put_contents(
  15.         "app/security/acl.data",
  16.         serialize($acl)
  17.     );
  18. } else {
  19.     // 返序列化
  20.     $acl = unserialize(
  21.         file_get_contents("app/security/acl.data")
  22.     );
  23. }
  25. // 使用ACL
  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.

ACL 事件（ACL Events）

如果需要的话 Phalcon\Acl 可以发送事件到 EventsManager 。 这里我们为acl绑定事件。 其中一些事件的处理结果如果返回了false则表示正在处理的操作会被中止。 支持如下的事件：

事件名触发条件能否中止操作
beforeCheckAccess在权限检查之前触发Yes
afterCheckAccess在权限检查之后触发No

下面的例子中展示了如何绑定事件到此组件：

  1. <?php
  3. use Phalcon\Acl\Adapter\Memory as AclList;
  4. use Phalcon\Events\Event;
  5. use Phalcon\Events\Manager as EventsManager;
  7. // ...
  9. // 创建事件管理器
  10. $eventsManager = new EventsManager();
  12. // 绑定事件类型为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. // 绑定eventsManager到ACL组件
  30. $acl->setEventsManager($eventsManager);

自定义适配器（Implementing your own adapters）

开发者要创建自己的扩展或已存在适配器则需要实现此 Phalcon\Acl\AdapterInterface 接口。