API Documentation

Zend/Acl.php

Show: inherited
Table of Contents

Zend Framework

LICENSE

This source file is subject to the new BSD license that is bundled with this package in the file LICENSE.txt. It is also available through the world-wide-web at this URL: http://framework.zend.com/license/new-bsd If you did not receive a copy of the license and are unable to obtain it through the world-wide-web, please send an email to license@zend.com so we can send you a copy immediately.

Category
Zend  
Copyright
Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)  
License
New BSD License  
Package
Zend_Acl  
Version
$Id: Acl.php 24772 2012-05-07 01:16:52Z adamlundrigan $  

\Zend_Acl

Package: Zend\Acl

Category
Zend  
Copyright
Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)  
License
New BSD License  

Constants

Constant  TYPE_ALLOW = 'TYPE_ALLOW'

Rule type: allow

Constant  TYPE_DENY = 'TYPE_DENY'

Rule type: deny

Constant  OP_ADD = 'OP_ADD'

Rule operation: add

Constant  OP_REMOVE = 'OP_REMOVE'

Rule operation: remove

Properties

PropertyprotectedString  $_isAllowedPrivilege= 'null'

Default valuenullDetails
Type
String
Propertyprotected\Zend_Acl_Resource_Interface  $_isAllowedResource= 'null'

Default valuenullDetails
Type
\Zend_Acl_Resource_Interface
Propertyprotected\Zend_Acl_Role_Interface  $_isAllowedRole= 'null'

Default valuenullDetails
Type
\Zend_Acl_Role_Interface
Propertyprotectedarray  $_resources= 'array()'

Resource tree

Default valuearray()Details
Type
array
Propertyprotected\Zend_Acl_Role_Registry  $_roleRegistry= 'null'

Role registry

Default valuenullDetails
Type
\Zend_Acl_Role_Registry
Propertyprotectedarray  $_rules= 'array( 'allResources' => array( 'allRoles' => array( 'allPrivileges' => array( 'type' => self::TYPE_DENY'

ACL rules; whitelist (deny everything to all) by default

Default valuearray( 'allResources' => array( 'allRoles' => array( 'allPrivileges' => array( 'type' => self::TYPE_DENYDetails
Type
array

Methods

methodprotected_getRoleRegistry( ) : \Zend_Acl_Role_Registry

Returns the Role registry for this ACL

If no Role registry has been created yet, a new default Role registry is created and returned.

Returns
Type Description
\Zend_Acl_Role_Registry
methodprotected_getRuleType( \Zend_Acl_Resource_Interface $resource = null, \Zend_Acl_Role_Interface $role = null, string $privilege = null ) : string|null

Returns the rule type associated with the specified Resource, Role, and privilege combination.

If a rule does not exist or its attached assertion fails, which means that the rule is not applicable, then this method returns null. Otherwise, the rule type applies and is returned as either TYPE_ALLOW or TYPE_DENY.

If $resource or $role is null, then this means that the rule must apply to all Resources or Roles, respectively.

If $privilege is null, then the rule must apply to all privileges.

If all three parameters are null, then the default ACL rule type is returned, based on whether its assertion method passes.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface
$role \Zend_Acl_Role_Interface
$privilege string
Returns
Type Description
string|null
methodprotected_getRules( \Zend_Acl_Resource_Interface $resource = null, \Zend_Acl_Role_Interface $role = null, boolean $create = false ) : array|null

Returns the rules associated with a Resource and a Role, or null if no such rules exist

If either $resource or $role is null, this means that the rules returned are for all Resources or all Roles, respectively. Both can be null to return the default rule set for all Resources and all Roles.

If the $create parameter is true, then a rule set is first created and then returned to the caller.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface
$role \Zend_Acl_Role_Interface
$create boolean
Returns
Type Description
array|null
methodprotected_roleDFSAllPrivileges( \Zend_Acl_Role_Interface $role, \Zend_Acl_Resource_Interface $resource = null ) : boolean|null

Performs a depth-first search of the Role DAG, starting at $role, in order to find a rule allowing/denying $role access to all privileges upon $resource

This method returns true if a rule is found and allows access. If a rule exists and denies access, then this method returns false. If no applicable rule is found, then this method returns null.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface
$resource \Zend_Acl_Resource_Interface
Returns
Type Description
boolean|null
methodprotected_roleDFSOnePrivilege( \Zend_Acl_Role_Interface $role, \Zend_Acl_Resource_Interface $resource = null, string $privilege = null ) : boolean|null

Performs a depth-first search of the Role DAG, starting at $role, in order to find a rule allowing/denying $role access to a $privilege upon $resource

This method returns true if a rule is found and allows access. If a rule exists and denies access, then this method returns false. If no applicable rule is found, then this method returns null.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface
$resource \Zend_Acl_Resource_Interface
$privilege string
Returns
Type Description
boolean|null
Throws
Exception Description
\Zend_Acl_Exception
methodprotected_roleDFSVisitAllPrivileges( \Zend_Acl_Role_Interface $role, \Zend_Acl_Resource_Interface $resource = null, array $dfs = null ) : boolean|null

Visits an $role in order to look for a rule allowing/denying $role access to all privileges upon $resource

This method returns true if a rule is found and allows access. If a rule exists and denies access, then this method returns false. If no applicable rule is found, then this method returns null.

This method is used by the internal depth-first search algorithm and may modify the DFS data structure.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface
$resource \Zend_Acl_Resource_Interface
$dfs array
Returns
Type Description
boolean|null
Throws
Exception Description
\Zend_Acl_Exception
methodprotected_roleDFSVisitOnePrivilege( \Zend_Acl_Role_Interface $role, \Zend_Acl_Resource_Interface $resource = null, string $privilege = null, array $dfs = null ) : boolean|null

Visits an $role in order to look for a rule allowing/denying $role access to a $privilege upon $resource

This method returns true if a rule is found and allows access. If a rule exists and denies access, then this method returns false. If no applicable rule is found, then this method returns null.

This method is used by the internal depth-first search algorithm and may modify the DFS data structure.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface
$resource \Zend_Acl_Resource_Interface
$privilege string
$dfs array
Returns
Type Description
boolean|null
Throws
Exception Description
\Zend_Acl_Exception
methodpublicadd( \Zend_Acl_Resource_Interface $resource, \Zend_Acl_Resource_Interface|string $parent = null ) : \Zend_Acl

Adds a Resource having an identifier unique to the ACL

The $parent parameter may be a reference to, or the string identifier for, the existing Resource from which the newly added Resource will inherit.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface
$parent \Zend_Acl_Resource_Interface|string
Returns
Type Description
\Zend_Acl Provides a fluent interface
Throws
Exception Description
\Zend_Acl_Exception
Details
Deprecated
in version 1.9.1 and will be available till 2.0. New code should use addResource() instead.  
methodpublicaddResource( \Zend_Acl_Resource_Interface|string $resource, \Zend_Acl_Resource_Interface|string $parent = null ) : \Zend_Acl

Adds a Resource having an identifier unique to the ACL

The $parent parameter may be a reference to, or the string identifier for, the existing Resource from which the newly added Resource will inherit.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface|string
$parent \Zend_Acl_Resource_Interface|string
Returns
Type Description
\Zend_Acl Provides a fluent interface
Throws
Exception Description
\Zend_Acl_Exception
methodpublicaddRole( \Zend_Acl_Role_Interface|string $role, \Zend_Acl_Role_Interface|string|array $parents = null ) : \Zend_Acl

Adds a Role having an identifier unique to the registry

The $parents parameter may be a reference to, or the string identifier for, a Role existing in the registry, or $parents may be passed as an array of these - mixing string identifiers and objects is ok - to indicate the Roles from which the newly added Role will directly inherit.

In order to resolve potential ambiguities with conflicting rules inherited from different parents, the most recently added parent takes precedence over parents that were previously added. In other words, the first parent added will have the least priority, and the last parent added will have the highest priority.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
$parents \Zend_Acl_Role_Interface|string|array
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl_Role_Registry::add()  
methodpublicallow( \Zend_Acl_Role_Interface|string|array $roles = null, \Zend_Acl_Resource_Interface|string|array $resources = null, string|array $privileges = null, \Zend_Acl_Assert_Interface $assert = null ) : \Zend_Acl

Adds an "allow" rule to the ACL

Parameters
Name Type Description
$roles \Zend_Acl_Role_Interface|string|array
$resources \Zend_Acl_Resource_Interface|string|array
$privileges string|array
$assert \Zend_Acl_Assert_Interface
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl::setRule()  
methodpublicdeny( \Zend_Acl_Role_Interface|string|array $roles = null, \Zend_Acl_Resource_Interface|string|array $resources = null, string|array $privileges = null, \Zend_Acl_Assert_Interface $assert = null ) : \Zend_Acl

Adds a "deny" rule to the ACL

Parameters
Name Type Description
$roles \Zend_Acl_Role_Interface|string|array
$resources \Zend_Acl_Resource_Interface|string|array
$privileges string|array
$assert \Zend_Acl_Assert_Interface
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl::setRule()  
methodpublicget( \Zend_Acl_Resource_Interface|string $resource ) : \Zend_Acl_Resource_Interface

Returns the identified Resource

The $resource parameter can either be a Resource or a Resource identifier.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface|string
Returns
Type Description
\Zend_Acl_Resource_Interface
Throws
Exception Description
\Zend_Acl_Exception
Details
Used_by
\Zend_Acl::setRule()  
Used_by
\Zend_Acl::isAllowed()  
methodpublicgetRegisteredRoles( ) : array

Returns
Type Description
array of registered roles (Deprecated)
Details
Deprecated
Deprecated since version 1.10 (December 2009)  
methodpublicgetResources( ) : array

Returns
Type Description
array of registered resources
methodpublicgetRole( \Zend_Acl_Role_Interface|string $role ) : \Zend_Acl_Role_Interface

Returns the identified Role

The $role parameter can either be a Role or Role identifier.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
Returns
Type Description
\Zend_Acl_Role_Interface
Details
Uses
\Zend_Acl_Role_Registry::get()  
methodpublicgetRoles( ) : array

Returns an array of registered roles.

Note that this method does not return instances of registered roles, but only the role identifiers.

Returns
Type Description
array of registered roles
methodpublichas( \Zend_Acl_Resource_Interface|string $resource ) : boolean

Returns true if and only if the Resource exists in the ACL

The $resource parameter can either be a Resource or a Resource identifier.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface|string
Returns
Type Description
boolean
methodpublichasRole( \Zend_Acl_Role_Interface|string $role ) : boolean

Returns true if and only if the Role exists in the registry

The $role parameter can either be a Role or a Role identifier.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
Returns
Type Description
boolean
Details
Uses
\Zend_Acl_Role_Registry::has()  
methodpublicinherits( \Zend_Acl_Resource_Interface|string $resource, \Zend_Acl_Resource_Interface|string $inherit, boolean $onlyParent = false ) : boolean

Returns true if and only if $resource inherits from $inherit

Both parameters may be either a Resource or a Resource identifier. If $onlyParent is true, then $resource must inherit directly from $inherit in order to return true. By default, this method looks through the entire inheritance tree to determine whether $resource inherits from $inherit through its ancestor Resources.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface|string
$inherit \Zend_Acl_Resource_Interface|string
$onlyParent boolean
Returns
Type Description
boolean
Throws
Exception Description
\Zend_Acl_Resource_Registry_Exception
methodpublicinheritsRole( \Zend_Acl_Role_Interface|string $role, \Zend_Acl_Role_Interface|string $inherit, boolean $onlyParents = false ) : boolean

Returns true if and only if $role inherits from $inherit

Both parameters may be either a Role or a Role identifier. If $onlyParents is true, then $role must inherit directly from $inherit in order to return true. By default, this method looks through the entire inheritance DAG to determine whether $role inherits from $inherit through its ancestor Roles.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
$inherit \Zend_Acl_Role_Interface|string
$onlyParents boolean
Returns
Type Description
boolean
Details
Uses
\Zend_Acl_Role_Registry::inherits()  
methodpublicisAllowed( \Zend_Acl_Role_Interface|string $role = null, \Zend_Acl_Resource_Interface|string $resource = null, string $privilege = null ) : boolean

Returns true if and only if the Role has access to the Resource

The $role and $resource parameters may be references to, or the string identifiers for, an existing Resource and Role combination.

If either $role or $resource is null, then the query applies to all Roles or all Resources, respectively. Both may be null to query whether the ACL has a "blacklist" rule (allow everything to all). By default, Zend_Acl creates a "whitelist" rule (deny everything to all), and this method would return false unless this default has been overridden (i.e., by executing $acl->allow()).

If a $privilege is not provided, then this method returns false if and only if the Role is denied access to at least one privilege upon the Resource. In other words, this method returns true if and only if the Role is allowed all privileges on the Resource.

This method checks Role inheritance using a depth-first traversal of the Role registry. The highest priority parent (i.e., the parent most recently added) is checked first, and its respective parents are checked similarly before the lower-priority parents of the Role are checked.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
$resource \Zend_Acl_Resource_Interface|string
$privilege string
Returns
Type Description
boolean
Details
Uses
\Zend_Acl::get()  
Uses
\Zend_Acl_Role_Registry::get()  
methodpublicremove( \Zend_Acl_Resource_Interface|string $resource ) : \Zend_Acl

Removes a Resource and all of its children

The $resource parameter can either be a Resource or a Resource identifier.

Parameters
Name Type Description
$resource \Zend_Acl_Resource_Interface|string
Returns
Type Description
\Zend_Acl Provides a fluent interface
Throws
Exception Description
\Zend_Acl_Exception
methodpublicremoveAll( ) : \Zend_Acl

Removes all Resources

Returns
Type Description
\Zend_Acl Provides a fluent interface
methodpublicremoveAllow( \Zend_Acl_Role_Interface|string|array $roles = null, \Zend_Acl_Resource_Interface|string|array $resources = null, string|array $privileges = null ) : \Zend_Acl

Removes "allow" permissions from the ACL

Parameters
Name Type Description
$roles \Zend_Acl_Role_Interface|string|array
$resources \Zend_Acl_Resource_Interface|string|array
$privileges string|array
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl::setRule()  
methodpublicremoveDeny( \Zend_Acl_Role_Interface|string|array $roles = null, \Zend_Acl_Resource_Interface|string|array $resources = null, string|array $privileges = null ) : \Zend_Acl

Removes "deny" restrictions from the ACL

Parameters
Name Type Description
$roles \Zend_Acl_Role_Interface|string|array
$resources \Zend_Acl_Resource_Interface|string|array
$privileges string|array
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl::setRule()  
methodpublicremoveRole( \Zend_Acl_Role_Interface|string $role ) : \Zend_Acl

Removes the Role from the registry

The $role parameter can either be a Role or a Role identifier.

Parameters
Name Type Description
$role \Zend_Acl_Role_Interface|string
Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl_Role_Registry::remove()  
methodpublicremoveRoleAll( ) : \Zend_Acl

Removes all Roles from the registry

Returns
Type Description
\Zend_Acl Provides a fluent interface
Details
Uses
\Zend_Acl_Role_Registry::removeAll()  
methodpublicsetRule( string $operation, string $type, \Zend_Acl_Role_Interface|string|array $roles = null, \Zend_Acl_Resource_Interface|string|array $resources = null, string|array $privileges = null, \Zend_Acl_Assert_Interface $assert = null ) : \Zend_Acl

Performs operations on ACL rules

The $operation parameter may be either OP_ADD or OP_REMOVE, depending on whether the user wants to add or remove a rule, respectively:

OP_ADD specifics:

 A rule is added that would allow one or more Roles access to [certain $privileges
 upon] the specified Resource(s).

OP_REMOVE specifics:

 The rule is removed only in the context of the given Roles, Resources, and privileges.
 Existing rules to which the remove operation does not apply would remain in the
 ACL.

The $type parameter may be either TYPE_ALLOW or TYPE_DENY, depending on whether the rule is intended to allow or deny permission, respectively.

The $roles and $resources parameters may be references to, or the string identifiers for, existing Resources/Roles, or they may be passed as arrays of these - mixing string identifiers and objects is ok - to indicate the Resources and Roles to which the rule applies. If either $roles or $resources is null, then the rule applies to all Roles or all Resources, respectively. Both may be null in order to work with the default rule of the ACL.

The $privileges parameter may be used to further specify that the rule applies only to certain privileges upon the Resource(s) in question. This may be specified to be a single privilege with a string, and multiple privileges may be specified as an array of strings.

If $assert is provided, then its assert() method must return true in order for the rule to apply. If $assert is provided with $roles, $resources, and $privileges all equal to null, then a rule having a type of:

 TYPE_ALLOW will imply a type of TYPE_DENY, and

 TYPE_DENY will imply a type of TYPE_ALLOW

when the rule's assertion fails. This is because the ACL needs to provide expected behavior when an assertion upon the default ACL rule fails.

Parameters
Name Type Description
$operation string
$type string
$roles \Zend_Acl_Role_Interface|string|array
$resources \Zend_Acl_Resource_Interface|string|array
$privileges string|array
$assert \Zend_Acl_Assert_Interface
Returns
Type Description
\Zend_Acl Provides a fluent interface
Throws
Exception Description
\Zend_Acl_Exception
Details
Used_by
\Zend_Acl::allow()  
Used_by
\Zend_Acl::deny()  
Used_by
\Zend_Acl::removeAllow()  
Used_by
\Zend_Acl::removeDeny()  
Uses
\Zend_Acl_Role_Registry::get()  
Uses
\Zend_Acl::get()  
Documentation was generated by DocBlox 0.15.1.