vendor/zendframework/zend-permissions-acl/doc/book/advanced.md

   1 # Advanced Usage
   2
   3 ## Storing ACL Data for Persistence
   4
   5 zend-permissions-acl was designed in such a way that it does not require any
   6 particular backend technology such as a database or cache server for storage of the ACL data. Its
   7 complete PHP implementation enables customized administration tools to be built upon
   8 `Zend\Permissions\Acl\Acl` with relative ease and flexibility. Many situations require some form of
   9 interactive maintenance of the ACL, and `Zend\Permissions\Acl\Acl` provides methods for setting
  10 up, and querying against, the access controls of an application.
  11
  12 Storage of ACL data is therefore left as a task for the developer, since use cases are expected to
  13 vary widely for various situations. Because `Zend\Permissions\Acl\Acl` is serializable, ACL
  14 objects may be serialized with PHP's [serialize() function](http://php.net/serialize), and the
  15 results may be stored anywhere the developer should desire, such as a file, database, or caching
  16 mechanism.
  17
  18 ## Writing Conditional ACL Rules with Assertions
  19
  20 Sometimes a rule for allowing or denying a role access to a resource should not
  21 be absolute, but dependent upon various criteria. For example, suppose that
  22 certain access should be allowed, but only between the hours of 8:00am and
  23 5:00pm. Another example would be denying access because a request comes from an
  24 IP address that has been flagged as a source of abuse.
  25 `Zend\Permissions\Acl\Acl` has built-in support for implementing rules based
  26 on whatever conditions the developer needs.
  27
  28 `Zend\Permissions\Acl\Acl` provides support for conditional rules with
  29 `Zend\Permissions\Acl\Assertion\AssertionInterface`. In order to use the rule assertion interface, a
  30 developer writes a class that implements the `assert()` method of the interface:
  31
  32 ```php
  33 use Zend\Permissions\Acl\Acl;
  34 use Zend\Permissions\Acl\Assertion\AssertionInterface;
  35 use Zend\Permissions\Acl\Role\RoleInterface;
  36 use Zend\Permissions\Acl\Resource\ResourceInterface;
  37
  38 class CleanIPAssertion implements AssertionInterface
  39 {
  40     public function assert(
  41         Acl $acl,
  42         RoleInterface $role = null,
  43         ResourceInterface $resource = null,
  44         $privilege = null
  45     ) {
  46         return $this->_isCleanIP($_SERVER['REMOTE_ADDR']);
  47     }
  48
  49     protected function _isCleanIP($ip)
  50     {
  51         // ...
  52     }
  53 }
  54 ```
  55
  56 Once an assertion class is available, the developer must supply an instance of
  57 the assertion class when assigning conditional rules. A rule that is created
  58 with an assertion only applies when the assertion method returns `TRUE`.
  59
  60 ```php
  61 use Zend\Permissions\Acl\Acl;
  62
  63 $acl = new Acl();
  64 $acl->allow(null, null, null, new CleanIPAssertion());
  65 ```
  66
  67 The above code creates a conditional allow rule that allows access to all
  68 privileges on everything by everyone, except when the requesting IP is
  69 "blacklisted". If a request comes in from an IP that is not considered "clean",
  70 then the allow rule does not apply. Since the rule applies to all roles, all
  71 resources, and all privileges, an "unclean" IP would result in a denial of
  72 access. This is a special case, however, and it should be understood that in all
  73 other cases (i.e., where a specific role, resource, or privilege is specified
  74 for the rule), a failed assertion results in the rule not applying, and other
  75 rules would be used to determine whether access is allowed or denied.
  76
  77 The `assert()` method of an assertion object is passed the ACL, role,
  78 resource, and privilege to which the authorization query (i.e., `isAllowed()`)
  79 applies, in order to provide a context for the assertion class to determine its
  80 conditions where needed.