Phalcon Auth

Auth\AbstractAuthDispatcherListener

Shared enforcement algorithm for the Cli, Mvc and Micro auth listeners. The subclass provides the action name and context from its event source, the action-kind label used in the access-denied exception, and (Mvc only) a forward handler for Access::redirectTo().

Enforcement is fail-open: when the manager has no active access (Manager::getAccess() === null) every dispatch is allowed. A policy activated via Manager::access() persists across forwards and nested dispatches in the same request until it is replaced.

Uses Phalcon\Auth\Exceptions\AccessDenied · Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\Manager

Method Summary

Properties

Methods

__construct()

public function __construct( Manager $manager );

enforce()

protected function enforce(
    string $actionName,
    array $context = [],
    mixed $forwardHandler = null
): bool;

Runs the access check for the given action name. Returns true when the dispatch should proceed, false when a forward was issued, and throws when access is denied without a redirect target.

The guard is fetched only when an access is active, so the no-op path works without a default guard.

getActionType()

abstract protected function getActionType(): string;

Returns the kind label used by AccessDenied (e.g. ‘task’, ‘action’, ‘route’).

Auth\Access\AbstractAccess

Uses Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Properties

Methods

getExceptActions()

public function getExceptActions(): array;

getOnlyActions()

public function getOnlyActions(): array;

isAllowed()

public function isAllowed(
    Guard $guard,
    string $actionName,
    array $context = []
): bool;

redirectTo()

public function redirectTo(): array|null;

setExceptActions()

public function setExceptActions( array $exceptActions = [] ): void;

setOnlyActions()

public function setOnlyActions( array $onlyActions = [] ): void;

allowedIf()

abstract protected function allowedIf( Guard $guard ): bool;

Whether the gate’s base condition holds for the given identity.

Auth\Access\AccessLocator

Service locator for Phalcon\Auth access gates. Utilizes the container to obtain the service. For the Phalcon\Container\Container one can use autowiring. For the Phalcon\Di\Di, one needs to register the gates in it to be used here (the binary gates also resolve unregistered through Di’s class builder).

@extends AbstractLocator<Access>

Uses Phalcon\Auth\Internal\ContainerResolver · Phalcon\Contracts\Auth\Access\Access · Phalcon\Support\AbstractLocator

Method Summary

Methods

newInstance()

public function newInstance( string $name ): object;

Resolve a fresh gate instance from the container.

Gates carry per-activation state (the only/except action filters), so resolution must yield a fresh instance: new() on the Container bypasses the instance cache; on the legacy Di, get() builds unregistered classes and non-shared services fresh (register gates non-shared).

getExceptionClass()

protected function getExceptionClass(): string;

getInterfaceClass()

protected function getInterfaceClass(): string;

getServices()

protected function getServices(): array;

Auth\Access\Acl

ACL-backed access gate. Checks the authenticated user’s role against a Phalcon\Acl adapter: the ACL component is taken from the ‘handler’ context key (prefixed with ‘module’ and the module separator when present) and the ACL access is the action name. The ‘params’ context key is passed through to the ACL adapter for callable rules.

Filter semantics differ from the binary gates: except = bypass the gate for the listed actions; only = the gate applies to the listed actions exclusively (everything else is allowed).

Role resolution: no user resolves to the configured guest role; a user implementing Phalcon\Acl\RoleAwareInterface supplies its role name; any other user is rejected with an exception.

Uses Phalcon\Acl\Adapter\AdapterInterface · Phalcon\Acl\RoleAwareInterface · Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\DoesNotImplement · Phalcon\Auth\Exceptions\MissingHandlerContext · Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Properties

Methods

__construct()

public function __construct(
    AdapterInterface $acl,
    array $options = []
);

isAllowed()

public function isAllowed(
    Guard $guard,
    string $actionName,
    array $context = []
): bool;

allowedIf()

protected function allowedIf( Guard $guard ): bool;

Unused: this gate overrides isAllowed() in full. Fail closed to satisfy the abstract.

resolveRole()

protected function resolveRole( Guard $guard ): string;

Auth\Access\Auth

Uses Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Methods

allowedIf()

protected function allowedIf( Guard $guard ): bool;

Auth\Access\Guest

Uses Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Methods

allowedIf()

protected function allowedIf( Guard $guard ): bool;

Auth\Adapter\AbstractAdapter

@template TConfig of AdapterConfig

Uses Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\Adapter\AdapterConfig · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Encryption\Security\Security

Method Summary

Constants

Properties

Methods

__construct()

public function __construct(
    Security $hasher,
    AdapterConfig $config
);

getConfig()

public function getConfig(): AdapterConfig;

Returns the adapter configuration object.

getModel()

public function getModel(): string|null;

Returns the model class name, if configured.

validateCredentials()

public function validateCredentials(
    AuthUser $user,
    array $credentials
): bool;

Validates the supplied plaintext password against the user’s stored hash. Concrete adapters share this implementation; if your data source needs a different verification strategy, override it.

burnHash()

protected function burnHash(): void;

Runs a throwaway password verification against a fixed dummy hash so the user-not-found path performs the same hash work as a found path. Call it when a credential lookup misses to keep response time constant.

Auth\Adapter\AbstractArrayAdapter

Common base for adapters whose user records come from an in-memory list (Memory and Stream). Subclasses provide the row source via loadUsers(); everything else - credentials matching, hydration, the empty-credentials guard, and a default linear retrieveById - is shared here.

@template TConfig of AdapterConfig @extends AbstractAdapter<TConfig>

Uses Phalcon\Auth\AuthUser · Phalcon\Auth\Exceptions\DoesNotImplement · Phalcon\Contracts\Auth\Adapter\AdapterConfig · Phalcon\Contracts\Auth\AuthUser

Method Summary

Methods

retrieveByCredentials()

public function retrieveByCredentials( array $credentials ): AuthUserContract|null;

Walks the user list and returns the first row whose non-‘password’ keys all match strictly. Returns null when no row matches or when $credentials carries no identifying field at all (only ‘password’, or empty) - protects callers from the silent “first row wins” footgun.

retrieveById()

public function retrieveById( mixed $id ): AuthUserContract|null;

Default linear-scan implementation. Memory overrides this for an O(1) id-keyed lookup; Stream uses this as-is.

hasIdentifyingField()

protected function hasIdentifyingField( array $credentials ): bool;

Tests whether a credentials payload carries at least one identifying field (i.e. anything other than ‘password’). An empty payload - or a payload that only contains ‘password’ - is treated as “no lookup”.

hydrate()

protected function hydrate( array $row ): AuthUserContract;

Hydrates a raw user row into either the configured model class or a Phalcon\Auth\AuthUser value object.

loadUsers()

abstract protected function loadUsers(): array;

Returns the source list of user rows. Concrete subclasses decide where they come from (config array, JSON file, etc.).

matchesRow()

protected function matchesRow(
    array $row,
    array $credentials
): bool;

Strict per-key match of a row against credentials, skipping ‘password’.

Auth\Adapter\AdapterLocator

Service locator for Phalcon\Auth adapters. Utilizes the container to obtain the service. For the Phalcon\Container\Container one can use autowiring. For the Phalcon\Di\Di, one needs to register the gates in it to be used here.

@extends AbstractLocator<Adapter>

Uses Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Support\AbstractLocator

Method Summary

Methods

getExceptionClass()

protected function getExceptionClass(): string;

getInterfaceClass()

protected function getInterfaceClass(): string;

getServices()

protected function getServices(): array;

Auth\Adapter\Config\AbstractAdapterConfig

@todo Remove in v7. Kept only for backwards compatibility; compose Phalcon\Auth\Adapter\Config\Traits\ModelConfigTrait directly instead of extending this.

Uses Phalcon\Auth\Adapter\Config\Traits\ModelConfigTrait · Phalcon\Contracts\Auth\Adapter\AdapterConfig

Method Summary

Methods

__construct()

public function __construct( string $model = null );

Auth\Adapter\Config\MemoryAdapterConfig

Method Summary

Properties

Methods

__construct()

public function __construct(
    array $users = [],
    string $model = null
);

getUsers()

public function getUsers(): array;

Auth\Adapter\Config\ModelAdapterConfig

Uses Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\ConfigRequiresNonEmptyValue

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $model,
    string $idColumn = "id"
);

getIdColumn()

public function getIdColumn(): string;

getModel()

public function getModel(): string;

Auth\Adapter\Config\StreamAdapterConfig

Uses Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\ConfigRequiresNonEmptyValue

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $file,
    string $model = null
);

getFile()

public function getFile(): string;

Auth\Adapter\Memory

In-memory adapter - useful for tests and small read-only user lists.

@extends AbstractArrayAdapter<MemoryAdapterConfig>

Uses Phalcon\Auth\Adapter\Config\MemoryAdapterConfig · Phalcon\Auth\Internal\Options · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Encryption\Security\Security

Method Summary

Methods

__construct()

public function __construct(
    Security $hasher,
    MemoryAdapterConfig $config
);

fromOptions()

public static function fromOptions(
    Security $hasher,
    array $options
): static;

retrieveById()

public function retrieveById( mixed $id ): AuthUser|null;

Overridden for O(1) lookup via the id index built in the constructor.

loadUsers()

protected function loadUsers(): array;

Auth\Adapter\Model

Phalcon Model-backed adapter.

@extends AbstractAdapter<ModelAdapterConfig>

Uses Phalcon\Auth\Adapter\Config\ModelAdapterConfig · Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\DoesNotImplement · Phalcon\Auth\Internal\Options · Phalcon\Contracts\Auth\Adapter\RememberAdapter · Phalcon\Contracts\Auth\AuthRemember · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\RememberToken · Phalcon\Contracts\Encryption\Security\Security · Phalcon\Mvc\ModelInterface

Method Summary

Methods

__construct()

public function __construct(
    Security $hasher,
    ModelAdapterConfig $config
);

createRememberToken()

public function createRememberToken( AuthUser $user ): RememberToken;

Create and persist a new remember token for the user.

fromOptions()

public static function fromOptions(
    Security $hasher,
    array $options
): static;

retrieveByCredentials()

public function retrieveByCredentials( array $credentials ): AuthUser|null;

Find a user matching the given credentials (excluding ‘password’ key).

retrieveById()

public function retrieveById( mixed $id ): AuthUser|null;

retrieveByToken()

public function retrieveByToken(
    mixed $id,
    string $token,
    string $userAgent = null
): AuthUser|null;

Retrieve a user by the remember-me cookie payload.

Auth\Adapter\Stream

JSON file-backed adapter.

The file must contain a JSON array of user records: [{“id”:1,“email”:“a@b”,“password”:“<hashed>”}, …]

@extends AbstractArrayAdapter<StreamAdapterConfig>

Uses InvalidArgumentException · Phalcon\Auth\Adapter\Config\StreamAdapterConfig · Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\FileCannotRead · Phalcon\Auth\Exceptions\FileDoesNotContainJson · Phalcon\Auth\Exceptions\FileDoesNotExist · Phalcon\Auth\Exceptions\FileNotValidJson · Phalcon\Auth\Internal\Options · Phalcon\Contracts\Encryption\Security\Security · Phalcon\Support\Helper\Json\Decode · Phalcon\Traits\Php\FileTrait

Method Summary

Methods

__construct()

public function __construct(
    Security $hasher,
    StreamAdapterConfig $config
);

fromOptions()

public static function fromOptions(
    Security $hasher,
    array $options
): static;

loadUsers()

protected function loadUsers(): array;

Loads and decodes the JSON users file. Re-read on every call - if you need caching, wrap it.

Auth\AuthUser

Lightweight value object returned by array-backed adapters (Memory, Stream) when no application model class is configured.

Uses Phalcon\Auth\Exceptions\DataMustContainIdKey · Phalcon\Contracts\Auth\AuthUser

Method Summary

Properties

Methods

__construct()

public function __construct( array $data );

getAuthIdentifier()

public function getAuthIdentifier(): int|string;

getAuthPassword()

public function getAuthPassword(): string;

toArray()

public function toArray(): array;

Returns the underlying data array.

Auth\Cli\AuthDispatcherListener

Uses Phalcon\Auth\AbstractAuthDispatcherListener · Phalcon\Auth\Exception · Phalcon\Cli\Dispatcher · Phalcon\Events\Event

Method Summary

Methods

beforeExecuteRoute()

public function beforeExecuteRoute(
    Event $event,
    Dispatcher $dispatcher
): bool;

getActionType()

protected function getActionType(): string;

Auth\Exception

Exceptions thrown in Phalcon\Auth will use this class

Auth\Exceptions\AccessDenied

Access denied exception

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $type,
    string $name
);

Auth\Exceptions\AccessNotRegistered

Access gate name is not registered

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Auth\Exceptions\ActiveAccessRequired

No active access has been set on the manager

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct();

Auth\Exceptions\ConfigRequiresNonEmptyValue

Config requires non-empty value

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $configName,
    string $configKey,
    string $suffix = ""
);

assert()

public static function assert(
    mixed $value,
    string $configName,
    string $configKey,
    string $suffix = ""
): void;

Throws when the value is an empty string. A null value is treated as “not provided” and passes, so optional settings can reuse the same guard; callers that require presence reject null earlier. Keeps the empty-value check shared by every config class in one place.

Auth\Exceptions\DataMustContainIdKey

AuthUser data must contain “id”

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct();

Auth\Exceptions\DefaultGuardNotRegistered

No default guard registered

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct();

Auth\Exceptions\DoesNotImplement

Does not implement interface

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $type,
    string $name
);

assert()

public static function assert(
    mixed $value,
    mixed $interfaceName,
    string $type,
    string $name
): void;

Throws when value is not an instance of the given interface. Keeps the “must implement” guard shared across adapters, guards and the manager in one place.

Auth\Exceptions\FileCannotRead

Cannot read file

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $path );

Auth\Exceptions\FileDoesNotContainJson

File does not contain a JSON array

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $path );

Auth\Exceptions\FileDoesNotExist

File does not exist

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $path );

Auth\Exceptions\FileNotValidJson

Not a valid JSON

Uses Phalcon\Auth\Exception · Throwable

Method Summary

Methods

__construct()

public function __construct(
    string $path,
    Throwable $ex
);

Auth\Exceptions\GuardNotDefined

Guard name is not defined on the manager

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Auth\Exceptions\MissingHandlerContext

The Acl access gate is missing the required ‘handler’ context key

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct();

Auth\Exceptions\OptionRequiresArray

Option must be a non-empty array

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $context,
    string $key
);

Auth\Exceptions\OptionRequiresString

Option must be a non-empty string

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $context,
    string $key
);

Auth\Exceptions\SessionNamesMustDiffer

Session guard ‘name’ and ‘rememberName’ must differ

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct();

Auth\Exceptions\UnknownAdapter

Unknown auth adapter requested from the factory

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Auth\Exceptions\UnknownGuard

Unknown auth guard type requested from the factory

Uses Phalcon\Auth\Exception

Method Summary

Methods

__construct()

public function __construct( string $type );

Auth\Guard\AbstractGuard

@template TConfig of GuardConfig

Uses Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\Guard\Guard · Phalcon\Contracts\Auth\Guard\GuardConfig · Phalcon\Events\AbstractEventsAware

Method Summary

Properties

Methods

__construct()

public function __construct(
    Adapter $adapter,
    GuardConfig $config
);

check()

public function check(): bool;

getAdapter()

public function getAdapter(): Adapter;

getConfig()

public function getConfig(): GuardConfig;

Returns the guard configuration object.

getLastUserAttempted()

public function getLastUserAttempted(): AuthUser|null;

guest()

public function guest(): bool;

hasUser()

public function hasUser(): bool;

id()

public function id(): int|string|null;

setAdapter()

public function setAdapter( Adapter $adapter ): static;

setUser()

public function setUser( AuthUser $user ): static;

hasValidCredentials()

protected function hasValidCredentials(
    mixed $user,
    array $credentials
): bool;

user should be ?AuthUser

Auth\Guard\Config\AbstractGuardConfig

Uses Phalcon\Contracts\Auth\Guard\GuardConfig

Auth\Guard\Config\SessionGuardConfig

Configuration for the Session guard. Holds the names under which the session key and remember-me cookie are stored. Defaults to ‘auth’ and ‘remember’; multi-guard apps can pass a $suffix (‘web’, ‘admin’, …) to derive ‘auth_web’ / ‘remember_web’ style names, or override either full name explicitly.

Uses Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\ConfigRequiresNonEmptyValue · Phalcon\Auth\Exceptions\SessionNamesMustDiffer

Method Summary

Constants

Methods

__construct()

public function __construct(
    string $suffix = null,
    string $name = null,
    string $rememberName = null,
    mixed $rememberTtl = null
);

getName()

public function getName(): string;

getRememberName()

public function getRememberName(): string;

getRememberTtl()

public function getRememberTtl(): int;

Auth\Guard\Config\TokenGuardConfig

Uses Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\ConfigRequiresNonEmptyValue

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $inputKey,
    string $storageKey
);

getInputKey()

public function getInputKey(): string;

getStorageKey()

public function getStorageKey(): string;

Auth\Guard\GuardLocator

Service locator for Phalcon\Auth guards. Utilizes the container to obtain the service. For Phalcon\Container\Container one can use autowiring; for Phalcon\Di\Di, register the guards in it before resolution.

@extends AbstractLocator<Guard>

Uses Phalcon\Contracts\Auth\Guard\Guard · Phalcon\Support\AbstractLocator

Method Summary

Methods

getExceptionClass()

protected function getExceptionClass(): string;

getInterfaceClass()

protected function getInterfaceClass(): string;

getServices()

protected function getServices(): array;

Auth\Guard\Session

@extends AbstractGuard<SessionGuardConfig>

Uses DateTimeImmutable · Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\DoesNotImplement · Phalcon\Auth\Guard\Config\SessionGuardConfig · Phalcon\Auth\Internal\ContainerResolver · Phalcon\Auth\Internal\Options · Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\Adapter\RememberAdapter · Phalcon\Contracts\Auth\AuthRemember · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\Guard\BasicAuth · Phalcon\Contracts\Auth\Guard\GuardStateful · Phalcon\Contracts\Auth\RememberToken · Phalcon\Http\RequestInterface · Phalcon\Http\Response\CookiesInterface · Phalcon\Session\ManagerInterface · Phalcon\Support\Helper\Json\Encode · Phalcon\Time\Clock\ClockInterface · Phalcon\Time\Clock\SystemClock

Method Summary

Properties

Methods

__construct()

public function __construct(
    Adapter $adapter,
    RequestInterface $request,
    CookiesInterface $cookies,
    SessionManagerInterface $session,
    SessionGuardConfig $config = null,
    ClockInterface $clock = null
);

attempt()

public function attempt(
    array $credentials = [],
    bool $remember = false
): bool;

basic()

public function basic(
    string $field = "email",
    array $extraConditions = []
): bool;

fromOptions()

public static function fromOptions(
    Adapter $adapter,
    mixed $container,
    array $options
): static;

getName()

public function getName(): string;

getRememberName()

public function getRememberName(): string;

login()

public function login(
    AuthUser $user,
    bool $remember = false
): void;

loginById()

public function loginById(
    mixed $id,
    bool $remember = false
): false|AuthUser;

logout()

public function logout(): void;

once()

public function once( array $credentials = [] ): bool;

onceBasic()

public function onceBasic(
    string $field = "email",
    array $extraConditions = []
): false|AuthUser;

user()

public function user(): AuthUser|null;

validate()

public function validate( array $credentials = [] ): bool;

viaRemember()

public function viaRemember(): bool;

attemptBasic()

protected function attemptBasic(
    string $field,
    array $extraConditions = []
): bool;

basicCredentials()

protected function basicCredentials( string $field ): array|null;

createRememberToken()

protected function createRememberToken( AuthUser $user ): RememberToken;

recaller()

protected function recaller(): UserRemember|null;

rememberUser()

protected function rememberUser( AuthUser $user ): void;

userFromRecaller()

protected function userFromRecaller( UserRemember $recaller ): AuthUser|null;

Auth\Guard\Token

@extends AbstractGuard<TokenGuardConfig>

Uses Phalcon\Auth\Guard\Config\TokenGuardConfig · Phalcon\Auth\Internal\ContainerResolver · Phalcon\Auth\Internal\Options · Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\AuthUser · Phalcon\Http\RequestInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    Adapter $adapter,
    RequestInterface $request,
    TokenGuardConfig $config
);

fromOptions()

public static function fromOptions(
    Adapter $adapter,
    mixed $container,
    array $options
): static;

getTokenForRequest()

public function getTokenForRequest(): string|null;

setRequest()

public function setRequest( RequestInterface $request ): static;

user()

public function user(): AuthUser|null;

validate()

public function validate( array $credentials = [] ): bool;

Auth\Guard\UserRemember

Value object representing the contents of a remember-me cookie.

Uses InvalidArgumentException · Phalcon\Support\Helper\Json\Decode

Method Summary

Properties

Methods

__construct()

public function __construct( mixed $payload );

Accepts either the raw JSON cookie value (string) or the already decoded associative array. Malformed input degrades to an empty payload so callers can read getters without null-guarding.

getId()

public function getId(): int|string|null;

getToken()

public function getToken(): string;

getUserAgent()

public function getUserAgent(): string;

Auth\Internal\ContainerResolver

Internal single source of truth for resolving services from either the new Phalcon\Container\Container or the legacy Phalcon\Di\Di. Not part of the public API.

Intent is Container-first; the legacy Di is supported “with provisions”: definitions must be pre-registered (no autowiring), the one exception being the fresh path, which lets Di build an unregistered but existing class via its class builder.

All legacy-Di failures are normalized to Phalcon\Container\Exceptions so callers and userland catch a single exception family.

Uses Phalcon\Container\Exceptions\Exception · Phalcon\Contracts\Container\Service\Collection · Phalcon\Di\DiInterface · Phalcon\Di\Exception

Method Summary

Methods

ensureContainer()

public static function ensureContainer( mixed $container ): void;

Validates that the value is a supported container.

requireService()

public static function requireService(
    mixed $container,
    array $candidates,
    string $context
): object;

Resolves the first candidate service name that the container can provide, as a shared instance. Used for framework services (request, cookies, session) whose container key may vary between application setups.

resolveCandidate()

public static function resolveCandidate(
    mixed $container,
    array $options,
    string $key,
    string $fqn,
    string $shortName,
    string $context
): object;

Convenience composition of serviceCandidates() + requireService(): resolves the first bound candidate for a framework service whose container key may vary, using the options override or the [interface FQN, conventional short name] fallback.

resolveFresh()

public static function resolveFresh(
    mixed $container,
    string $name
): object;

Resolves a fresh instance: new() on the Container (bypasses the instance cache); get() on the legacy Di (fresh for unregistered or non-shared services). On Di, an unregistered but existing class is still built via the class builder.

serviceCandidates()

public static function serviceCandidates(
    array $options,
    string $key,
    string $fqn,
    string $shortName
): array;

Builds the ordered candidate list for a framework service: an explicit override from options[‘services’][key] if present, otherwise the interface FQN followed by the conventional short name.

Auth\Internal\Options

Internal option-parsing helpers shared by adapter / guard fromOptions() implementations. Not part of the public API.

Uses Phalcon\Auth\Exception · Phalcon\Auth\Exceptions\OptionRequiresArray · Phalcon\Auth\Exceptions\OptionRequiresString

Method Summary

Methods

arrayOption()

public static function arrayOption(
    array $options,
    string $key,
    array $defaultValue
): array;

requireArray()

public static function requireArray(
    array $options,
    string $key,
    string $context
): array;

requireString()

public static function requireString(
    array $options,
    string $key,
    string $context
): string;

stringOrNull()

public static function stringOrNull(
    array $options,
    string $key
): string|null;

Auth\Manager

Composes guards (authentication) and access gates (authorization) behind a single facade. Guard-specific behavior is reached through Manager::guard(); callers narrow with instanceof against the relevant capability interface (GuardStateful, BasicAuth, etc.).

Uses Phalcon\Auth\Access\AccessLocator · Phalcon\Auth\Exceptions\AccessNotRegistered · Phalcon\Auth\Exceptions\ActiveAccessRequired · Phalcon\Auth\Exceptions\DefaultGuardNotRegistered · Phalcon\Auth\Exceptions\DoesNotImplement · Phalcon\Auth\Exceptions\GuardNotDefined · Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\Guard\Guard · Phalcon\Contracts\Auth\Guard\GuardStateful · Phalcon\Contracts\Auth\Manager

Method Summary

Properties

Methods

__construct()

public function __construct( AccessLocator $accessFactory );

access()

public function access( string $accessName ): self;

addAccessList()

public function addAccessList( array $accessList ): self;

addGuard()

public function addGuard(
    string $nameGuard,
    Guard $guard,
    bool $isDefault = false
): self;

attempt()

public function attempt(
    array $credentials = [],
    bool $remember = false
): bool;

check()

public function check(): bool;

except()

public function except( string $actions ): self;

getAccess()

public function getAccess(): Access|null;

getAccessList()

public function getAccessList(): array;

getDefaultGuard()

public function getDefaultGuard(): Guard|null;

getGuards()

public function getGuards(): array;

guard()

public function guard( string $name = null ): Guard;

id()

public function id(): int|string|null;

logout()

public function logout(): void;

only()

public function only( string $actions ): self;

setAccess()

public function setAccess( Access $access ): self;

setDefaultGuard()

public function setDefaultGuard( Guard $guard ): self;

user()

public function user(): AuthUser|null;

validate()

public function validate( array $credentials = [] ): bool;

Auth\ManagerFactory

Single entry-point factory that builds a fully wired Phalcon\Auth\Manager from a config tree. Framework-shared services (RequestInterface, CookiesInterface, SessionManagerInterface) are resolved from the injected container so the manager wires against the real application singletons, not separately constructed copies.

[ ‘guards’ => [ ‘web’ => [ ‘type’ => ‘session’, ‘default’ => true, ‘adapter’ => [ ‘name’ => ‘model’, ‘options’ => [ ‘model’ => User::class ], ], ‘options’ => [], ], ‘api’ => [ ‘type’ => ‘token’, ‘adapter’ => [ ‘name’ => ‘model’, ‘options’ => [ ‘model’ => User::class ] ], ‘options’ => [ ‘inputKey’ => ‘api_token’, ‘storageKey’ => ‘api_token’ ], ], ], ‘access’ => [ ‘auth’ => \Phalcon\Auth\Access\Auth::class, ‘guest’ => \Phalcon\Auth\Access\Guest::class, ], ]

Uses Phalcon\Auth\Access\AccessLocator · Phalcon\Auth\Adapter\AdapterLocator · Phalcon\Auth\Exceptions\UnknownAdapter · Phalcon\Auth\Exceptions\UnknownGuard · Phalcon\Auth\Guard\GuardLocator · Phalcon\Auth\Internal\ContainerResolver · Phalcon\Auth\Internal\Options · Phalcon\Config\ConfigInterface · Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\Guard\Guard · Phalcon\Contracts\Container\Service\Collection · Phalcon\Di\DiInterface · Phalcon\Encryption\Security

Method Summary

Properties

Methods

__construct()

public function __construct(
    Security $hasher,
    mixed $container,
    AdapterLocator $adapterLocator = null,
    GuardLocator $guardLocator = null,
    AccessLocator $accessLocator = null
);

load()

public function load( mixed $config ): Manager;

buildAdapter()

protected function buildAdapter(
    AdapterLocator $locator,
    array $cfg
): Adapter;

buildGuard()

protected function buildGuard(
    GuardLocator $locator,
    string $type,
    Adapter $adapter,
    array $options
): Guard;

Auth\Micro\AuthMicroListener

Listener that enforces the active Phalcon\Auth access gate on each Micro route execution. Attach to the events manager:

$eventsManager->attach(‘micro’, new AuthMicroListener($manager)); $app->setEventsManager($eventsManager);

The action name is the matched route’s name, falling back to the route pattern when the route is unnamed. The ACL component is the configured component name (default ‘Micro’). redirectTo() is ignored - Micro has no forward mechanism.

No-op when no active access has been set on the manager.

Uses Phalcon\Auth\AbstractAuthDispatcherListener · Phalcon\Auth\Exception · Phalcon\Contracts\Auth\Manager · Phalcon\Events\Event · Phalcon\Mvc\Micro · Phalcon\Mvc\RouterInterface · Phalcon\Mvc\Router\RouteInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    Manager $manager,
    string $componentName = "Micro"
);

beforeExecuteRoute()

public function beforeExecuteRoute(
    Event $event,
    Micro $application
): bool;

getActionType()

protected function getActionType(): string;

Auth\Mvc\AuthDispatcherListener

Listener that enforces the active Phalcon\Auth access gate on each MVC dispatch. Attach to the events manager:

$eventsManager->attach(‘dispatch’, new AuthDispatcherListener($manager));

No-op when no active access has been set on the manager.

Uses Phalcon\Auth\AbstractAuthDispatcherListener · Phalcon\Auth\Exception · Phalcon\Events\Event · Phalcon\Mvc\Dispatcher

Method Summary

Methods

beforeExecuteRoute()

public function beforeExecuteRoute(
    Event $event,
    Dispatcher $dispatcher
): bool;

getActionType()

protected function getActionType(): string;