Phalcon Acl

Acl\AbstractElement

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.

Uses Phalcon\Acl\Traits\ItemTrait

Acl\Adapter\AbstractAdapter

Functionality common to all adapters

Uses Phalcon\Acl\Enum · Phalcon\Events\AbstractEventsAware · Phalcon\Events\EventsAwareInterface

Method Summary

Properties

Methods

getActiveAccess()

public function getActiveAccess(): string|null;

Returns the access which the list is checking if a role can access it

getActiveComponent()

public function getActiveComponent(): string|null;

Returns the component which the list is checking if some role can access it

getActiveRole()

public function getActiveRole(): string|null;

Returns the role which the list is checking if it’s allowed to certain component/access

getDefaultAction()

public function getDefaultAction(): int;

Returns the default action

setDefaultAction()

public function setDefaultAction( int $defaultAccess ): void;

Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)

Acl\Adapter\AdapterInterface

Interface for Phalcon\Acl adapters

Uses Phalcon\Contracts\Acl\Adapter\Adapter

Acl\Adapter\Memory

Manages ACL lists in memory

$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);
    }
}

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\ForbiddenDelimiter · 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 · Phalcon\Contracts\Acl\AclTypes · ReflectionClass · ReflectionException · ReflectionFunction · ReflectionNamedType

Method Summary

Properties

Methods

addComponent()

public function addComponent(
    mixed $componentValue,
    mixed $accessList
): bool;

Adds a component to the ACL list

Access names can be a particular action, for instance search, update delete etc. or a list of them.

Example:

// 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()

public function addComponentAccess(
    string $componentName,
    mixed $accessList
): bool;

Adds access to components

The guard below is the validation, so the parameter stays var here. The accepted values are documented on the contract.

addInherit()

public function addInherit(
    string $roleName,
    mixed $roleToInherits
): bool;

Add a role which inherits from an existing role

$acl->addRole("administrator", "consultant");
$acl->addRole("administrator", ["consultant", "consultant2"]);

addRole()

public function addRole(
    mixed $role,
    mixed $accessInherits = null
): bool;

Adds a role to the ACL list. The second parameter lets to inherit access from an existing role

$acl->addRole(
    new Phalcon\Acl\Role("administrator"),
    "consultant"
);

$acl->addRole("administrator", "consultant");
$acl->addRole("administrator", ["consultant", "consultant2"]);

allow()

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.

// 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()

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.

// 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()

public function dropComponentAccess(
    string $componentName,
    mixed $accessList
): void;

Removes access from a component

getActiveFunction()

public function getActiveFunction(): mixed;

Returns the latest function used to acquire access

getActiveFunctionCustomArgumentsCount()

public function getActiveFunctionCustomArgumentsCount(): int;

Returns number of additional arguments(excluding role and resource) for active function

getActiveKey()

public function getActiveKey(): string|null;

Returns the last composite key used to acquire access.

getComponents()

public function getComponents(): ComponentInterface[];

Return an array with every component registered in the list

getInheritedRoles()

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()

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()

public function getRoles(): RoleInterface[];

Return an array with every role registered in the list

isAllowed()

public function isAllowed(
    mixed $roleName,
    mixed $componentName,
    string $access,
    array|null $parameters = null
): bool;

Check whether a role is allowed to access an action from a component

// 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()

public function isComponent( string $componentName ): bool;

Check whether component exist in the components list

isRole()

public function isRole( string $roleName ): bool;

Check whether role exist in the roles list

setNoArgumentsDefaultAction()

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

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

Uses Phalcon\Acl\Component · Phalcon\Acl\Enum · Phalcon\Acl\Exceptions\InvalidSnapshot · Phalcon\Acl\Role · Phalcon\Contracts\Acl\AclTypes · Phalcon\Contracts\Acl\Adapter\Persistable · Phalcon\Storage\Adapter\AdapterInterface

Method Summary

Constants

Properties

Methods

__construct()

public function __construct(
    StorageInterface $storage,
    string $key = "acl-data"
);

load()

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()

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

This class defines component entity and its description

Uses Phalcon\Acl\Exceptions\ForbiddenDelimiter · Phalcon\Acl\Exceptions\ForbiddenWildcard

Method Summary

Methods

__construct()

public function __construct(
    string $name,
    string|null $description = null
);

Component constructor.

Acl\ComponentAwareInterface

Interface for ACL Component aware objects

Uses Phalcon\Contracts\Acl\ComponentAware

Acl\ComponentInterface

Interface for Phalcon\Acl\Component

Uses Phalcon\Contracts\Acl\Component

Acl\Enum

Constants for Phalcon\Acl\Adapter adapters

Constants

Acl\Exception

Class for exceptions thrown by Phalcon\Acl

Acl\Exceptions\AccessRuleNotFound

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $accessName,
    string $componentName
);

Acl\Exceptions\CircularInheritanceError

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct( string $roleName );

Acl\Exceptions\ElementNotFound

Uses Phalcon\Acl\Exception

Acl\Exceptions\ForbiddenDelimiter

The “!” character separates the role, component and access parts of the internal ACL keys, so a name that contains it would make two different tuples share one key.

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct( string $elementType );

Acl\Exceptions\ForbiddenWildcard

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct( string $elementType );

Acl\Exceptions\InvalidAccessList

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct();

Acl\Exceptions\InvalidComponentImplementation

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct();

Acl\Exceptions\InvalidRoleImplementation

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct();

Acl\Exceptions\InvalidRoleType

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct();

Acl\Exceptions\InvalidSnapshot

Uses Phalcon\Acl\Exception

Acl\Exceptions\MissingFunctionParameters

Uses Phalcon\Acl\Exception

Acl\Exceptions\ParameterTypeMismatch

Uses Phalcon\Acl\Exception

Acl\Exceptions\RoleNotFoundException

Uses Phalcon\Acl\Exception

Method Summary

Methods

__construct()

public function __construct( string $roleName );

Acl\Role

This class defines role entity and its description

Uses Phalcon\Acl\Exceptions\ForbiddenDelimiter · Phalcon\Acl\Exceptions\ForbiddenWildcard

Method Summary

Methods

__construct()

public function __construct(
    string $name,
    string|null $description = null
);

Role constructor.

Acl\RoleAwareInterface

Interface for ACL Role aware objects

Uses Phalcon\Contracts\Acl\RoleAware

Acl\RoleInterface

Interface for Phalcon\Acl\Role

Uses Phalcon\Contracts\Acl\Role

Acl\Traits\ItemTrait

This class defines role/component names and their descriptions

Used by Phalcon\Acl\AbstractElement

Method Summary

Properties

Methods

__toString()

public function __toString(): string;

getDescription()

public function getDescription(): string|null;

getName()

public function getName(): string;