Access Control Lists
The Caridea\Acl\Acl
interface is the contract for Access Control Lists in this library. Implementations of this class are meant to be serializable. It's recommended that they're also immutable, but this is not a requirement. ACLs can have parent ACLs, which are consulted in the event that the child contains no applicable rules for a test.
Working with the Interface
There are three methods of note when working with an Acl
:
can
– Provided anarray
ofSubject
s and a verb, this method returnstrue
if any of theSubject
s can perform the provided verb- The parent ACL will be consulted if this one has no corresponding rules.
getParent
– Returns the parentAcl
ornull
if one was not specifiedgetTarget
– Returns theTarget
for which thisAcl
applies
There are two bundled implementations of the Caridea\Acl\Acl
interface: Caridea\Acl\RuleAcl
and Caridea\Acl\DenyAcl
.
DenyAcl
The Caridea\Acl\DenyAcl
class is a no-op implementation which always denies access. It's useful for unit tests and as a null object.
RuleAcl
The Caridea\Acl\RuleAcl
class is an immutable and serializable list of access rules.
Rules
The RuleAcl
internally stores Caridea\Acl\Rule
objects. They are immutable, serializable classes which either grant or deny a subject access to a verb.
$admin = \Caridea\Acl\Subject::role('admin');
$blocked = \Caridea\Acl\Subject::role('blocked');
$allow = \Caridea\Acl\Rule::allow($admin, ['read', 'write', 'delete']);
$deny = \Caridea\Acl\Rule::deny($blocked, ['read', 'write', 'delete']);
Creating a Rule ACL
To create a RuleAcl
, simply provide everything necessary to the constructor.
$subjects = [$admin, $blocked];
$rules = [$allow, $deny];
$target = new \Caridea\Acl\Target('foo', 'bar');
$parent = new \Caridea\Acl\DenyAcl();
$acl = new \Caridea\Acl\RuleAcl(
$target,
$subjects,
$rules,
$parent
);
$acl->can([$admin], 'read');
// true
$acl->can([$blocked], 'read');
// false
$acl->can([$blocked], 'dance');
// false; delegates to parent, since no rules exist for the verb "dance"
$acl->can([\Caridea\Acl\Subject::principal('nobody@example.com')], 'read');
// InvalidArgumentException("This ACL does not apply to one of the provided subjects")