---
title: "Phalcon Acl"
version: "5.17"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Acl
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Acl\AbstractElement
Abstract
Source on GitHub
Shared base for ACL Role and Component entities: a name and an optional
description.
@todo Remove in v7. Kept only for backwards compatibility; the logic now
lives in `Phalcon\Acl\Traits\ItemTrait` - compose that trait directly
instead of extending this class.
- **`Phalcon\Acl\AbstractElement`**
- [`Phalcon\Acl\Component`](#aclcomponent)
- [`Phalcon\Acl\Role`](#aclrole)
__Uses__ `Phalcon\Acl\Traits\ItemTrait`
## Acl\Adapter\AbstractAdapter
Abstract
Source on GitHub
Adapter for Phalcon\Acl adapters
- [`Phalcon\Events\AbstractEventsAware`](/5.17/api/phalcon_events/#eventsabstracteventsaware)
- **`Phalcon\Acl\Adapter\AbstractAdapter`** - implements [`Phalcon\Acl\Adapter\AdapterInterface`](#acladapteradapterinterface), [`Phalcon\Events\EventsAwareInterface`](/5.17/api/phalcon_events/#eventseventsawareinterface)
- [`Phalcon\Acl\Adapter\Memory`](#acladaptermemory)
__Uses__ `Phalcon\Acl\Enum` · `Phalcon\Events\AbstractEventsAware` · `Phalcon\Events\EventsAwareInterface`
### Method Summary
### Properties
protected
int
$accessGranted = Enum::DENY
Access Granted
protected
string|null
$activeAccess = null
Active access which the list is checking if some role can access it
protected
string|null
$activeComponent = null
Component which the list is checking if some role can access it
protected
string|null
$activeRole = null
Role which the list is checking if it's allowed to certain component/access
protected
int
$defaultAccess = Enum::DENY
Default access
### Methods
Public · 5
getActiveAccess()
```php
public function getActiveAccess(): string|null;
```
Active access which the list is checking if some role can access it
getActiveComponent()
```php
public function getActiveComponent(): string|null;
```
Component which the list is checking if some role can access it
getActiveRole()
```php
public function getActiveRole(): string|null;
```
Role which the list is checking if it's allowed to certain
component/access
getDefaultAction()
```php
public function getDefaultAction(): int;
```
Returns the default ACL access level
setDefaultAction()
```php
public function setDefaultAction( int $defaultAccess ): void;
```
Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)
## Acl\Adapter\AdapterInterface
Interface
Source on GitHub
Interface for Phalcon\Acl adapters
- [`Phalcon\Contracts\Acl\Adapter\Adapter`](/5.17/api/phalcon_contracts/#contractsacladapteradapter)
- **`Phalcon\Acl\Adapter\AdapterInterface`**
__Uses__ `Phalcon\Contracts\Acl\Adapter\Adapter`
## Acl\Adapter\Memory
Class
Source on GitHub
Manages ACL lists in memory
```php
$acl = new \Phalcon\Acl\Adapter\Memory();
$acl->setDefaultAction(
\Phalcon\Acl\Enum::DENY
);
// Register roles
$roles = [
"users" => new \Phalcon\Acl\Role("Users"),
"guests" => new \Phalcon\Acl\Role("Guests"),
];
foreach ($roles as $role) {
$acl->addRole($role);
}
// Private area components
$privateComponents = [
"companies" => ["index", "search", "new", "edit", "save", "create", "delete"],
"products" => ["index", "search", "new", "edit", "save", "create", "delete"],
"invoices" => ["index", "profile"],
];
foreach ($privateComponents as $componentName => $actions) {
$acl->addComponent(
new \Phalcon\Acl\Component($componentName),
$actions
);
}
// Public area components
$publicComponents = [
"index" => ["index"],
"about" => ["index"],
"session" => ["index", "register", "start", "end"],
"contact" => ["index", "send"],
];
foreach ($publicComponents as $componentName => $actions) {
$acl->addComponent(
new \Phalcon\Acl\Component($componentName),
$actions
);
}
// Grant access to public areas to both users and guests
foreach ($roles as $role) {
foreach ($publicComponents as $component => $actions) {
$acl->allow($role->getName(), $component, "*");
}
}
// Grant access to private area to role Users
foreach ($privateComponents as $component => $actions) {
foreach ($actions as $action) {
$acl->allow("Users", $component, $action);
}
}
```
- [`Phalcon\Events\AbstractEventsAware`](/5.17/api/phalcon_events/#eventsabstracteventsaware)
- [`Phalcon\Acl\Adapter\AbstractAdapter`](#acladapterabstractadapter)
- **`Phalcon\Acl\Adapter\Memory`**
- [`Phalcon\Acl\Adapter\Storage`](#acladapterstorage)
__Uses__ `Phalcon\Acl\Component` · `Phalcon\Acl\ComponentAwareInterface` · `Phalcon\Acl\ComponentInterface` · `Phalcon\Acl\Enum` · `Phalcon\Acl\Exceptions\AccessRuleNotFound` · `Phalcon\Acl\Exceptions\CircularInheritanceError` · `Phalcon\Acl\Exceptions\ElementNotFound` · `Phalcon\Acl\Exceptions\InvalidAccessList` · `Phalcon\Acl\Exceptions\InvalidComponentImplementation` · `Phalcon\Acl\Exceptions\InvalidRoleImplementation` · `Phalcon\Acl\Exceptions\InvalidRoleType` · `Phalcon\Acl\Exceptions\MissingFunctionParameters` · `Phalcon\Acl\Exceptions\ParameterTypeMismatch` · `Phalcon\Acl\Exceptions\RoleNotFoundException` · `Phalcon\Acl\Role` · `Phalcon\Acl\RoleAwareInterface` · `Phalcon\Acl\RoleInterface` · `ReflectionClass` · `ReflectionFunction` · `ReflectionNamedType`
### Method Summary
public
__construct()
Phalcon\Acl\Adapter\Memory constructor
public
bool
addComponent(mixed $componentValue,mixed $accessList)
Adds a component to the ACL list
public
bool
addComponentAccess(string $componentName,mixed $accessList)
Adds access to components
public
bool
addInherit(string $roleName,mixed $roleToInherits)
Do a role inherit from another existing role
public
bool
addRole(mixed $role,mixed $accessInherits = null)
Adds a role to the ACL list. Second parameter allows inheriting access data from other existing role
public
void
allow(string $roleName,string $componentName,mixed $access,mixed $func = null)
Allow access to a role on a component. You can use * as wildcard
public
void
deny(string $roleName,string $componentName,mixed $access,mixed $func = null)
Deny access to a role on a component. You can use * as wildcard
public
void
dropComponentAccess(string $componentName,mixed $accessList)
Removes access from a component
public
mixed
getActiveFunction()
Returns the latest function used to acquire access
public
int
getActiveFunctionCustomArgumentsCount()
Returns number of additional arguments(excluding role and resource) for active function
public
string|null
getActiveKey()
Returns the latest key used to acquire access
public
ComponentInterface[]
getComponents()
Return an array with every component registered in the list
public
array
getInheritedRoles( string $roleName = "" )
Returns the inherited roles for a passed role name. If no role name
public
int
getNoArgumentsDefaultAction()
Returns the default ACL access level for no arguments provided in
public
RoleInterface[]
getRoles()
Return an array with every role registered in the list
public
bool
isAllowed(mixed $roleName,mixed $componentName,string $access,array $parameters = null)
Check whether a role is allowed to access an action from a component
public
bool
isComponent( string $componentName )
Check whether component exist in the components list
public
bool
isRole( string $roleName )
Check whether role exist in the roles list
public
void
setNoArgumentsDefaultAction( int $defaultAccess )
Sets the default access level (Phalcon\Enum::ALLOW or Phalcon\Enum::DENY)
### Properties
protected
array
$access
Access
protected
array
$accessList
Access List
protected
mixed
$activeFunction
Returns the latest function used to acquire access
protected
int
$activeFunctionCustomArgumentsCount = 0
Returns number of additional arguments(excluding role and resource) for active function
protected
string|null
$activeKey = null
Returns the latest key used to acquire access
protected
array
$components
Components
protected
array
$componentsNames
Component Names
protected
array
$functions
Function List
protected
int
$noArgumentsDefaultAction = Enum::DENY
Default action for no arguments is allow
protected
array
$roleInherits
Role Inherits
protected
array
$roles
Roles
### Methods
Public · 19
__construct()
```php
public function __construct();
```
Phalcon\Acl\Adapter\Memory constructor
addComponent()
```php
public function addComponent(
mixed $componentValue,
mixed $accessList
): bool;
```
Adds a component to the ACL list
Access names can be a particular action, by example
search, update, delete, etc. or a list of them
Example:
```php
// Add a component to the list allowing access to an action
$acl->addComponent(
new Phalcon\Acl\Component("customers"),
"search"
);
$acl->addComponent("customers", "search");
// Add a component with an access list
$acl->addComponent(
new Phalcon\Acl\Component("customers"),
[
"create",
"search",
]
);
$acl->addComponent(
"customers",
[
"create",
"search",
]
);
```
addComponentAccess()
```php
public function addComponentAccess(
string $componentName,
mixed $accessList
): bool;
```
Adds access to components
addInherit()
```php
public function addInherit(
string $roleName,
mixed $roleToInherits
): bool;
```
Do a role inherit from another existing role
```php
$acl->addRole("administrator", "consultant");
$acl->addRole("administrator", ["consultant", "consultant2"]);
```
addRole()
```php
public function addRole(
mixed $role,
mixed $accessInherits = null
): bool;
```
Adds a role to the ACL list. Second parameter allows inheriting access data from other existing role
If the role already exists this method returns `false` and the
`accessInherits` argument is ignored; the existing role is left
unchanged.
```php
$acl->addRole(
new Phalcon\Acl\Role("administrator"),
"consultant"
);
$acl->addRole("administrator", "consultant");
$acl->addRole("administrator", ["consultant", "consultant2"]);
```
allow()
```php
public function allow(
string $roleName,
string $componentName,
mixed $access,
mixed $func = null
): void;
```
Allow access to a role on a component. You can use `*` as wildcard
A `*` role is an eager snapshot: it expands to the roles that exist when
`allow()` is called, so roles added afterwards do not inherit the grant.
```php
// Allow access to guests to search on customers
$acl->allow("guests", "customers", "search");
// Allow access to guests to search or create on customers
$acl->allow("guests", "customers", ["search", "create"]);
// Allow access to any role to browse on products
$acl->allow("*", "products", "browse");
// Allow access to any role to perform any action on any component
$acl->allow("*", "*", "*");
```
deny()
```php
public function deny(
string $roleName,
string $componentName,
mixed $access,
mixed $func = null
): void;
```
Deny access to a role on a component. You can use `*` as wildcard
A `*` role is an eager snapshot: it expands to the roles that exist when
`deny()` is called, so roles added afterwards do not inherit the rule.
```php
// Deny access to guests to search on customers
$acl->deny("guests", "customers", "search");
// Deny access to guests to search or create on customers
$acl->deny("guests", "customers", ["search", "create"]);
// Deny access to any role to browse on products
$acl->deny("*", "products", "browse");
// Deny access to any role to perform any action on any component
$acl->deny("*", "*", "*");
```
dropComponentAccess()
```php
public function dropComponentAccess(
string $componentName,
mixed $accessList
): void;
```
Removes access from a component
getActiveFunction()
```php
public function getActiveFunction(): mixed;
```
Returns the latest function used to acquire access
getActiveFunctionCustomArgumentsCount()
```php
public function getActiveFunctionCustomArgumentsCount(): int;
```
Returns number of additional arguments(excluding role and resource) for active function
getActiveKey()
```php
public function getActiveKey(): string|null;
```
Returns the latest key used to acquire access
getComponents()
```php
public function getComponents(): ComponentInterface[];
```
Return an array with every component registered in the list
getInheritedRoles()
```php
public function getInheritedRoles( string $roleName = "" ): array;
```
Returns the inherited roles for a passed role name. If no role name
has been specified it will return the whole array. If the role has not
been found it returns an empty array
getNoArgumentsDefaultAction()
```php
public function getNoArgumentsDefaultAction(): int;
```
Returns the default ACL access level for no arguments provided in
`isAllowed` action if a `func` (callable) exists for `accessKey`
getRoles()
```php
public function getRoles(): RoleInterface[];
```
Return an array with every role registered in the list
isAllowed()
```php
public function isAllowed(
mixed $roleName,
mixed $componentName,
string $access,
array $parameters = null
): bool;
```
Check whether a role is allowed to access an action from a component
```php
// Does andres have access to the customers component to create?
$acl->isAllowed("andres", "Products", "create");
// Do guests have access to any component to edit?
$acl->isAllowed("guests", "*", "edit");
```
isComponent()
```php
public function isComponent( string $componentName ): bool;
```
Check whether component exist in the components list
isRole()
```php
public function isRole( string $roleName ): bool;
```
Check whether role exist in the roles list
setNoArgumentsDefaultAction()
```php
public function setNoArgumentsDefaultAction( int $defaultAccess ): void;
```
Sets the default access level (`Phalcon\Enum::ALLOW` or `Phalcon\Enum::DENY`)
for no arguments provided in isAllowed action if there exists func for
accessKey
## Acl\Adapter\Storage
Class
Source on GitHub
ACL adapter that persists its policy to any Phalcon\Storage backend
(Redis, Apcu, Stream, Memcached, ...) as a whole-policy snapshot.
The snapshot is a versioned, scalar-only structure: roles and components are
stored as `name => description` maps and rebuilt into objects on load, so the
snapshot round-trips through any serializer (php, json, igbinary, msgpack).
Callable (closure) rules are not serializable. Any access key backed by a
closure is persisted as DENY, so a reloaded policy fails closed until the
closure is re-registered after load().
Single-writer contract: mutations are in-memory until save() is called, and
save() writes the whole snapshot (last-write-wins, no atomic check-and-set).
Use external locking when multiple processes write the same key.
@see Persistable
- [`Phalcon\Events\AbstractEventsAware`](/5.17/api/phalcon_events/#eventsabstracteventsaware)
- [`Phalcon\Acl\Adapter\AbstractAdapter`](#acladapterabstractadapter)
- [`Phalcon\Acl\Adapter\Memory`](#acladaptermemory)
- **`Phalcon\Acl\Adapter\Storage`** - implements [`Phalcon\Contracts\Acl\Adapter\Persistable`](/5.17/api/phalcon_contracts/#contractsacladapterpersistable)
__Uses__ `Phalcon\Acl\Component` · `Phalcon\Acl\Enum` · `Phalcon\Acl\Exceptions\InvalidSnapshot` · `Phalcon\Acl\Role` · `Phalcon\Contracts\Acl\Adapter\Persistable` · `Phalcon\Storage\Adapter\AdapterInterface`
### Method Summary
### Constants
### Properties
protected
string
$key
protected
StorageInterface
$storage
### Methods
Public · 3
__construct()
```php
public function __construct(
StorageInterface $storage,
string $key = "acl-data"
);
```
load()
```php
public function load(): bool;
```
Loads the policy snapshot from the backing store, replacing current
in-memory state. Returns false when no compatible snapshot exists; throws
Phalcon\Acl\Exceptions\InvalidSnapshot on an incompatible version or a
malformed structure.
save()
```php
public function save(): bool;
```
Persists the policy snapshot. Closure-backed access keys are written as
DENY (fail closed); roles/components are written as scalar name =>
description maps for serializer independence.
## Acl\Component
Class
Source on GitHub
This class defines component entity and its description
- [`Phalcon\Acl\AbstractElement`](#aclabstractelement)
- **`Phalcon\Acl\Component`** - implements [`Phalcon\Acl\ComponentInterface`](#aclcomponentinterface)
__Uses__ `Phalcon\Acl\Exceptions\ForbiddenWildcard`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct(
string $name,
string $description = null
);
```
Phalcon\Acl\Component constructor
## Acl\ComponentAwareInterface
Interface
Source on GitHub
Interface for classes which could be used in allow method as RESOURCE
- [`Phalcon\Contracts\Acl\ComponentAware`](/5.17/api/phalcon_contracts/#contractsaclcomponentaware)
- **`Phalcon\Acl\ComponentAwareInterface`**
__Uses__ `Phalcon\Contracts\Acl\ComponentAware`
## Acl\ComponentInterface
Interface
Source on GitHub
Interface for Phalcon\Acl\Component
- [`Phalcon\Contracts\Acl\Component`](/5.17/api/phalcon_contracts/#contractsaclcomponent)
- **`Phalcon\Acl\ComponentInterface`**
__Uses__ `Phalcon\Contracts\Acl\Component`
## Acl\Enum
Class
Source on GitHub
Constants for Phalcon\Acl\Adapter adapters
- **`Phalcon\Acl\Enum`**
### Constants
int
ALLOW = 1
int
DENY = 0
## Acl\Exception
Class
Source on GitHub
Class for exceptions thrown by Phalcon\Acl
- `\Exception`
- **`Phalcon\Acl\Exception`**
- [`Phalcon\Acl\Exceptions\AccessRuleNotFound`](#aclexceptionsaccessrulenotfound)
- [`Phalcon\Acl\Exceptions\CircularInheritanceError`](#aclexceptionscircularinheritanceerror)
- [`Phalcon\Acl\Exceptions\ElementNotFound`](#aclexceptionselementnotfound)
- [`Phalcon\Acl\Exceptions\ForbiddenWildcard`](#aclexceptionsforbiddenwildcard)
- [`Phalcon\Acl\Exceptions\InvalidAccessList`](#aclexceptionsinvalidaccesslist)
- [`Phalcon\Acl\Exceptions\InvalidComponentImplementation`](#aclexceptionsinvalidcomponentimplementation)
- [`Phalcon\Acl\Exceptions\InvalidRoleImplementation`](#aclexceptionsinvalidroleimplementation)
- [`Phalcon\Acl\Exceptions\InvalidRoleType`](#aclexceptionsinvalidroletype)
- [`Phalcon\Acl\Exceptions\InvalidSnapshot`](#aclexceptionsinvalidsnapshot)
- [`Phalcon\Acl\Exceptions\MissingFunctionParameters`](#aclexceptionsmissingfunctionparameters)
- [`Phalcon\Acl\Exceptions\ParameterTypeMismatch`](#aclexceptionsparametertypemismatch)
- [`Phalcon\Acl\Exceptions\RoleNotFoundException`](#aclexceptionsrolenotfoundexception)
## Acl\Exceptions\AccessRuleNotFound
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\AccessRuleNotFound`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct(
string $accessName,
string $componentName
);
```
## Acl\Exceptions\CircularInheritanceError
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\CircularInheritanceError`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct( string $roleName );
```
## Acl\Exceptions\ElementNotFound
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\ElementNotFound`**
__Uses__ `Phalcon\Acl\Exception`
## Acl\Exceptions\ForbiddenWildcard
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\ForbiddenWildcard`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct( string $elementType );
```
## Acl\Exceptions\InvalidAccessList
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\InvalidAccessList`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Acl\Exceptions\InvalidComponentImplementation
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\InvalidComponentImplementation`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Acl\Exceptions\InvalidRoleImplementation
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\InvalidRoleImplementation`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Acl\Exceptions\InvalidRoleType
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\InvalidRoleType`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct();
```
## Acl\Exceptions\InvalidSnapshot
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\InvalidSnapshot`**
__Uses__ `Phalcon\Acl\Exception`
## Acl\Exceptions\MissingFunctionParameters
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\MissingFunctionParameters`**
__Uses__ `Phalcon\Acl\Exception`
## Acl\Exceptions\ParameterTypeMismatch
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\ParameterTypeMismatch`**
__Uses__ `Phalcon\Acl\Exception`
## Acl\Exceptions\RoleNotFoundException
Class
Source on GitHub
- `\Exception`
- [`Phalcon\Acl\Exception`](#aclexception)
- **`Phalcon\Acl\Exceptions\RoleNotFoundException`**
__Uses__ `Phalcon\Acl\Exception`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct( string $roleName );
```
## Acl\Role
Class
Source on GitHub
This class defines role entity and its description
- [`Phalcon\Acl\AbstractElement`](#aclabstractelement)
- **`Phalcon\Acl\Role`** - implements [`Phalcon\Acl\RoleInterface`](#aclroleinterface)
__Uses__ `Phalcon\Acl\Exceptions\ForbiddenWildcard`
### Method Summary
### Methods
Public · 1
__construct()
```php
public function __construct(
string $name,
string $description = null
);
```
Phalcon\Acl\Role constructor
## Acl\RoleAwareInterface
Interface
Source on GitHub
Interface for classes which could be used in allow method as ROLE
- [`Phalcon\Contracts\Acl\RoleAware`](/5.17/api/phalcon_contracts/#contractsaclroleaware)
- **`Phalcon\Acl\RoleAwareInterface`**
__Uses__ `Phalcon\Contracts\Acl\RoleAware`
## Acl\RoleInterface
Interface
Source on GitHub
Interface for Phalcon\Acl\Role
- [`Phalcon\Contracts\Acl\Role`](/5.17/api/phalcon_contracts/#contractsaclrole)
- **`Phalcon\Acl\RoleInterface`**
__Uses__ `Phalcon\Contracts\Acl\Role`
Source: https://docs.phalcon.io/5.17/api/phalcon_acl/index.mdx