Manager

Coordinates authentication state for PhalconKit applications.

The manager exposes a compact identity API on top of several lower-level traits: user lookup, session-backed identity storage, JWT claim handling, OAuth2 account linking, role inheritance, ACL role construction, and impersonation. It expects the application DI to provide the standard PhalconKit services used by those traits, including config, models, request, security, session, JWT, and bootstrap services.

Identity state is stored as a small payload keyed by the active JWT claim key. The payload normally lives in the session service; when identity.stateless is enabled it lives directly in the JWT claim so API clients can avoid server-side identity persistence. The primary payload keys are userId for the effective user and asUserId for the original user during impersonation. Login and password reset responses deliberately avoid exposing whether an email address exists unless validation has already failed, so downstream code should preserve that behavior when overriding the manager.

• Full name: \PhalconKit\Identity\Manager
• Parent class: \PhalconKit\Di\Injectable
• This class implements: \PhalconKit\Identity\ManagerInterface, \PhalconKit\Support\Options\OptionsInterface

Methods

get

Return the current identity payload.

public get(array|null $userExpose = null): array<string,mixed>

This method is the short public entry point used by controllers and API responses. It delegates to

• See: \PhalconKit\Identity\getIdentity() so subclasses only need to customize the detailed identity payload in one place.

Parameters:

Return Value:

Identity payload for the current request.

getIdentity

Build the current identity payload.

public getIdentity(array|null $userExpose = null): array{loggedInAs: bool, userAs: mixed, loggedIn: bool, user: mixed, roleList: array<string,object>, typeList: array<string,object>, groupList: array<string,object>}

The payload includes both the effective user and the original user when impersonating. Related role, type, and group lists are normalized into maps keyed by each related entity's getKey() value so ACL checks and API consumers can use stable identifiers without inspecting model relation internals.

Parameters:

Throws:

When a related role/type/group entity cannot provide a stable key. - LogicException

login

Validate credentials and establish the session identity.

public login(array<string,mixed> $params = []): array{loggedIn: bool, loggedInAs: bool, messages: \Phalcon\Messages\Messages, jwt?: string, refreshToken?: string, refreshed?: bool}

The login flow accepts an email address and password, validates both fields, checks the configured user model, and stores the authenticated userId in the identity payload. Missing users, disabled passwords, and invalid passwords all return the same generic login-failed message so the response does not reveal whether an account exists. Deleted users are rejected with a forbidden message after password verification succeeds. When stateless identity is enabled, successful responses also include a freshly signed JWT/refresh-token pair containing the new identity payload.

Successful login also refreshes the global model security roles from the effective ACL roles, allowing model behaviors to evaluate the newly authenticated identity immediately.

Parameters:

Throws:

When stateless token key generation fails. - Exception When stateless JWT creation fails. - ValidatorException When default PHP-session storage cannot renew the session before authenticating. - ServiceException

logout

Remove the current identity payload.

public logout(): array{loggedIn: bool, loggedInAs: bool, jwt?: string, refreshToken?: string, refreshed?: bool}

Logout clears the identity stored under the current claim key. It does not clear unrelated session data. Stateless clients receive a refreshed anonymous token response and must replace/discard any older authenticated token client-side; JWTs are not server-revoked without an application revocation strategy.

Return Value:

Login state after the identity has been removed.

Throws:

When stateless token key generation fails. - Exception When stateless JWT creation fails. - ValidatorException

reset

Request or redeem a time-limited, single-use password reset token.

public reset(array<string,mixed>|null $params = null): array<string,mixed>

New reset records use v1:<expiry>:<hash> in the existing resetToken column; legacy records are rejected and require a new reset request. identity.resetPassword.lifetime is seconds (default 1800). Token hashes use the same configured salt as verification. Raw tokens are delivered only through sendPasswordResetNotification(), never returned to clients.

Redemption atomically claims the stored token and saves the hashed password in one write-connection transaction. Custom persistence/password hooks must preserve the documented helper contracts. Existing sessions are not revoked automatically; applications own that policy and notification delivery.

Parameters:

Return Value:

Empty on success/unknown request email, or validation messages.

Throws:

When random generation or hashing fails. - Exception For invalid token lifetime. - ConfigurationException When a transaction cannot be owned or committed. - ServiceException

validatePasswordResetToken

Verify the stored reset record's format, expiry, and configured-salt hash.

protected validatePasswordResetToken(\PhalconKit\Models\Interfaces\UserInterface $user, string $record, string $token): bool

Custom record formats must retain expiry checks and reject legacy undated hashes. Validation alone does not consume the record; persistence must compare and consume the exact record atomically.

Parameters:

Return Value:

Whether the token matches an unexpired record.

persistPasswordReset

Atomically claim a reset record and persist the new password through model hooks.

protected persistPasswordReset(\PhalconKit\Models\Interfaces\UserInterface $user, string $record, string $password): bool

The default uses the mapped user id/resetToken columns and the user's write connection, which must support transactions. It refuses an existing outer transaction rather than committing or rolling back caller-owned work. Cleanup tolerates a save hook having already ended the transaction, preserving its original exception and restoring the in-memory credentials. Failed saves/claims roll back and restore the model's credential fields. Overrides for other stores must implement atomic compare-and-consume plus password persistence, and retain false-on-lost-race semantics.

Parameters:

Return Value:

True only after a successful commit; false for lost claims or save rejection.

Throws:

When transaction setup/commit fails. - ServiceException

rollbackActivePasswordResetTransaction

Roll back an owned transaction only if it remains active after save hooks.

private rollbackActivePasswordResetTransaction(\Phalcon\Contracts\Db\Adapter\Adapter $connection): void

Parameters:

setPasswordAfterReset

Set a securely hashed password before reset persistence.

protected setPasswordAfterReset(\PhalconKit\Models\Interfaces\UserInterface $user, string $password): void

Applications with a model setter/save hook that already hashes plaintext must override this helper to avoid double hashing. Other password policy checks belong in model validation and can reject save() transactionally.

Parameters:

sendPasswordResetNotification

Deliver a successfully persisted reset token through an application-owned channel.

protected sendPasswordResetNotification(\PhalconKit\Models\Interfaces\UserInterface $user, string $token, int $expiresAt): void

Override for mail/queue delivery. The default intentionally sends nothing; applications must provide delivery before exposing reset requests. Do not log tokens or expose them in HTTP responses. Delivery failures propagate.

Parameters:

collectList

Normalize a related model list into a key-indexed map.

private collectList(\PhalconKit\Mvc\ModelInterface|null $model, string $property, string $keyMethod = 'getKey'): array<string,object>

Identity payloads need stable role, type, and group keys regardless of whether relations were eager-loaded, staged as dirty related records, or assigned to public fixture properties in tests. This helper checks those sources in order and ignores missing or non-iterable values.

Parameters:

Return Value:

Related entities keyed by their stable key.

Throws:

When a related entity is not an object or does not implement the required key method. - LogicException

Inherited methods

getUser

Return the effective user or original impersonating user.

public getUser(bool $as = false, bool|null $force = null): \PhalconKit\Models\Interfaces\UserInterface|null

Unless $force is set, the method returns the cached instance for the requested slot. A fresh lookup reads userId or asUserId from the session identity payload and eager-loads role, group, and type relations through the configured user model.

Parameters:

Deleted users never authenticate. Model security suppression is restored even when a user lookup fails, including nested security operations. |

Return Value:

Active user model or null when missing or deleted.

clearIdentityCache

Clear effective/original users and cached model ACL roles after an identity change.

protected clearIdentityCache(): void

Custom identity persistence overrides must call this after replacing or removing their stored payload, before authorizing further model operations.

requireIdentityUser

Require the configured user model query to return the identity contract.

protected requireIdentityUser(mixed $user): \PhalconKit\Models\Interfaces\UserInterface

The identity manager can resolve the user model from application configuration, so the query result is a framework integration boundary. This helper keeps getUser() focused on session/user selection while failing clearly if the configured model does not implement the expected PhalconKit user interface.

Parameters:

Throws:

When the configured user model does not return the PhalconKit identity user contract. - ServiceException

setUser

Cache the effective user and invalidate cached model ACL roles.

public setUser(\PhalconKit\Models\Interfaces\UserInterface|null $user): void

Parameters:

getUserAs

Return the original user during impersonation.

public getUserAs(): \PhalconKit\Models\Interfaces\UserInterface|null

Return Value:

Original user or null when not impersonating.

setUserAs

Cache the original user and invalidate cached model ACL roles.

public setUserAs(\PhalconKit\Models\Interfaces\UserInterface|null $user): void

Parameters:

getUserId

Return the effective or original user's id.

public getUserId(bool $as = false): int|null

Parameters:

Return Value:

User id or null when no matching user is logged in.

getUserAsId

Return the original user's id during impersonation.

public getUserAsId(): int|null

Return Value:

Original user id or null when not impersonating.

getRoleList

Return roles associated with the current effective identity.

public getRoleList(): array<string,object>

Return Value:

Role entities keyed by their stable key.

getGroupList

Return groups associated with the current effective identity.

public getGroupList(): array<string,object>

Return Value:

Group entities keyed by their stable key.

getTypeList

Return types associated with the current effective identity.

public getTypeList(): array<string,object>

Return Value:

Type entities keyed by their stable key.

isLoggedIn

Check whether the effective or original user is logged in.

public isLoggedIn(bool $as = false, bool $force = false): bool

Parameters:

Return Value:

True when a matching user model can be resolved.

isLoggedInAs

Check whether the current session is impersonating another user.

public isLoggedInAs(bool $force = false): bool

Parameters:

Return Value:

True when asUserId resolves to a user.

findUserById

Find a user by primary key through the configured user model.

public findUserById(int $id): \PhalconKit\Models\Interfaces\UserInterface|null

Parameters:

Return Value:

Matching user or null.

findUserByEmail

Find a user by email through the configured user model.

public findUserByEmail(string $string): \PhalconKit\Models\Interfaces\UserInterface|null

Parameters:

Return Value:

Matching user or null.

getSessionKey

Return the configured identity session namespace.

public getSessionKey(bool $refresh = false): string

Parameters:

Return Value:

Configured session key with the optional refresh suffix.

removeSessionIdentity

Remove the identity payload and clear cached users and model ACL roles.

public removeSessionIdentity(): void

Overrides using custom storage must also call clearIdentityCache().

If no claim key is available, there is no addressable identity payload and the method intentionally becomes a no-op.

setSessionIdentity

Replace the identity payload under the active claim key and clear user/ACL caches.

public setSessionIdentity(array<string,mixed> $identity): void

Stateless storage preserves only token bookkeeping from the previous claim. Include any custom identity fields in the replacement payload explicitly. Overrides using custom storage must also call clearIdentityCache(). PHP-session storage renews the session ID before writing a non-empty userId, including login, OAuth2, impersonation, and authenticated refresh. The old session keeps unrelated data but loses this identity. Custom persistence overrides own equivalent credential-fixation protection; stateless identity does not resolve or renew the PHP session service.

Parameters:

Throws:

When the PHP session is inactive or cannot renew its ID. The replacement identity is not written on failure. - ServiceException

renewIdentitySession

Renew the active PHP session before assigning authenticated identity.

protected renewIdentitySession(string $key): void

Remove this identity before native regeneration persists the old session. Unrelated session values survive in both sessions; only the new session receives the replacement identity. The old anonymous session can expire normally, avoiding immediate deletion during concurrent requests.

Parameters:

Throws:

When renewal fails; an unchanged session retains its previous payload and never receives the replacement identity. - ServiceException

getSessionIdentity

Return the identity payload stored under the active claim key.

public getSessionIdentity(): array<string,mixed>

Return Value:

Empty when no key or payload exists.

hasSessionIdentity

Check whether an identity payload exists for the active claim key.

public hasSessionIdentity(): bool

Return Value:

True when both a claim key and matching session payload are present.

getKey

Return the active claim key used to address session identity storage.

public getKey(): string|null

Return Value:

Claim key or null when no usable claim has been resolved.

isStatelessIdentity

Check whether identity state should be carried only in JWT claims.

protected isStatelessIdentity(): bool

This setting does not disable the framework session service globally. It only changes where the identity payload is persisted, which keeps unrelated session consumers available for applications that still need them.

getJwtForStatelessIdentity

Return fresh JWT values after an identity state change when needed.

protected getJwtForStatelessIdentity(): array{jwt?: string, refreshToken?: string, refreshed?: bool}

Stateless clients must replace their token after login, logout, OAuth2 login, and impersonation changes because the identity payload lives in the token subject. Stateful clients keep receiving the legacy response shape because the session-backed payload has already changed server-side.

hasRole

Check whether the current identity has the requested roles.

public hasRole(array<int,string>|null $roles = null, bool $or = false, bool $inherit = true): bool

When inheritance is enabled, configured parent roles are added to the current role list before matching. With the legacy $or flag left at its default, the method returns true when any requested role matches. Passing true requires every requested role to match at the current level.

Parameters:

Return Value:

True if the user satisfies the role conditions, false otherwise.

has

Match one or more values against a haystack.

public has(array<int,mixed>|string|null $needles = null, array<int,string> $haystack = [], bool $or = false): bool

At the current level, the legacy $or flag behaves as follows: false returns true when any needle matches, and true returns true only when every needle matches. Each nested array flips the mode for that nested group, enabling expressions such as "all of these groups, where each group may contain any of these roles".

Examples:

$this->has(['dev', 'admin'], $roles); // 'dev' OR 'admin' $this->has(['dev', 'admin'], $roles, true); // 'dev' AND 'admin' $this->has([['dev', 'admin']], $roles, true); // ('dev' OR 'admin')

Parameters:

Return Value:

True when the expression matches the haystack.

getInheritedRoleList

Resolve inherited roles from the permissions configuration.

public getInheritedRoleList(array<int,string> $roleIndexList = []): array<int,string>

The method walks permissions.roles.<role>.inherit recursively, avoids re-processing roles it has already inspected, and returns a de-duplicated list. When no base or inherited role is present, guest is added. The universal everyone role is always included.

Parameters:

Return Value:

Unique inherited role names.

oauth2

Create/update an OAuth2 identity and log in its linked local user.

public oauth2(string $provider, string $providerUuid, string $accessToken, string|null $refreshToken = null, array<string,mixed>|null $meta = []): array{saved: bool, loggedIn: bool, loggedInAs: bool, messages: \Phalcon\Messages\Messages, jwt?: string, refreshToken?: string, refreshed?: bool}

If the provider identity is not linked yet and a local user is already logged in, the provider identity is attached to that user. Otherwise the saved provider identity must already contain a user id before login can succeed.

The models service resolves the configured OAuth2 class. Replacements must implement Oauth2Interface and return model instances (or null when absent) from findFirst(). New records use a fresh instance, never the cached model held by the resolver. Application validation and save hooks remain active.

Parameters:

Throws:

When OAuth provider fields cannot be sanitized. - Exception When validation cannot be configured. - Exception When stateless token key generation fails after a successful OAuth2 login. - Exception When stateless JWT creation fails after a successful OAuth2 login. - ValidatorException When the model mapping/lookup violates the OAuth2 contract, or PHP-session storage cannot renew before authenticating. - ServiceException

getJwt

Generate access and refresh tokens for the current claim.

public getJwt(bool $refresh = false): array{jwt: string, refreshToken: string, refreshed: bool}

When no claim key exists, a new UUID key is created. During refresh with session-backed identity storage, the existing identity payload is copied from the old key to the new key after the old storage entry is removed, which invalidates tokens tied to the old key while keeping the user logged in. In stateless identity mode, the payload is preserved directly in the claim so clients can carry it without PHP session storage; old signed JWTs remain valid until expiration or an application-level revocation strategy rejects them. Default PHP-session storage also renews its session ID during an authenticated refresh; clients must accept the replacement cookie.

Parameters:

Throws:

When token key generation fails. - Exception When JWT creation fails. - ValidatorException With status 401 when a supplied token is invalid, before session identity is read or rotated and before tokens are issued. - HttpException When PHP-session identity cannot be established after renewal. - ServiceException

getClaim

Resolve the current claim from request and session sources.

public getClaim(bool $refresh = false, bool $force = false): array<string,mixed>

Resolution order is refresh token, JWT request value, authorization header, then optional session fallback. The fallback is intentionally disabled by default because it couples token authentication to server-side session state, and is always skipped when identity.stateless is enabled.

Parameters:

Return Value:

Claim payload or an empty array when no supported credential is present.

Throws:

With status 401 when a supplied token fails parsing or validation. Invalid tokens never fall through to session fallback. - HttpException

setClaim

Replace the cached claim and invalidate cached users and model ACL roles.

public setClaim(array<string,mixed> $claim): void

Parameters:

getJwtToken

Build a signed JWT with Phalcon's JWT service.

public getJwtToken(string $id, array<string,mixed> $data = [], array<string,mixed> $options = []): string

Missing issuer and audience values default to the current request URI. Missing token id defaults to $id, and the subject defaults to the JSON encoded claim data.

Parameters:

Return Value:

Encoded JWT.

Throws:

When the JWT builder rejects the options. - ValidatorException

getClaimFromToken

Validate a JWT and return its decoded subject payload.

public getClaimFromToken(string $token, string|null $claim = null): array<string,mixed>

The token must match the current request URI as issuer and audience. When $claim is provided, it is used as the expected token id so access and refresh tokens cannot be exchanged.

Parameters:

Return Value:

Decoded sub payload or an empty array when the subject is missing/non-array.

Throws:

With status 401 when parsing or validation fails. Validation errors are enforced before decoding the subject; neither the token nor the validator's diagnostics are exposed in the exception. - HttpException

getClaimFromAuthorization

Resolve a claim from a bearer authorization header.

public getClaimFromAuthorization(array<int,string> $authorization): array<string,mixed>

Parameters:

Return Value:

Claim payload or an empty array when the header is not a bearer token.

Throws:

With status 401 when the bearer credential is malformed or its token is invalid. Unsupported schemes return []. - HttpException

getJsonRawBody

Return the request JSON body as an object.

private getJsonRawBody(): \stdClass

Phalcon throws for invalid JSON; identity credential lookup treats that as an empty body so malformed optional JSON does not prevent header/query credentials from being evaluated.

Return Value:

Parsed body or an empty object.

loginAs

Switch the current session to another user.

public loginAs(array<string,mixed> $params = []): array{messages?: \Phalcon\Messages\Messages, loggedIn: bool, loggedInAs: bool, jwt?: string, refreshToken?: string, refreshed?: bool}

The target userId must be present, numeric, and resolvable through the configured user model and must not be deleted. If the target id equals the current asUserId, the method treats the request as a return-to-self action and restores the original session.

Parameters:

Throws:

When stateless token key generation fails. - Exception When stateless JWT creation fails. - ValidatorException When default PHP-session storage cannot renew the session before changing identity. - ServiceException

logoutAs

Restore the original user from an impersonated session.

public logoutAs(): array{loggedIn: bool, loggedInAs: bool, jwt?: string, refreshToken?: string, refreshed?: bool}

If both userId and asUserId are present, the original id becomes the effective userId and the impersonation marker is removed.

Return Value:

Login state after the restore attempt.

Throws:

When stateless token key generation fails. - Exception When stateless JWT creation fails. - ValidatorException When default PHP-session storage cannot renew the session before restoring identity. - ServiceException

hasAclRole

Check whether the current identity has at least one (or all) of the given ACL roles.

public hasAclRole(array|null $roles = null, bool $or = false): bool

This method evaluates the provided role names against the effective ACL role set returned by

• See: \PhalconKit\Identity\Traits\getAclRoles(), not just the raw identity roles. As a result:

• Contextual roles such as ws, cli, and everyone are implicitly considered.

• The guest role may be present when no explicit identity roles exist.
• Inherited roles are already resolved and included.

Internally, this delegates to - See: \PhalconKit\Identity\Traits\has(), comparing: - the requested roles ($roles) - against the keys of the computed ACL role map

Parameters:

Return Value:

True if the role condition is satisfied, false otherwise.

getAclRoles

Build and return the effective ACL role set for the current identity.

public getAclRoles(array|null $roleList = null): array<string,\Phalcon\Acl\Role>

This method computes the final, authoritative list of ACL roles used by permission checks. The resulting role set is not a direct reflection of the identity’s stored roles; it is a context-aware, normalized, and expanded role map that accounts for execution context and role inheritance.

Resolution rules, applied in order:

1. Execution-context roles
2. ws is added when running under a WebSocket bootstrap.

3. cli is added when running under a console/CLI bootstrap.

4. Global role

5. everyone is always added, regardless of identity state.

6. Identity roles

7. If $roleList is provided, it is treated as the authoritative base role list.

8. Otherwise, roles are derived from the current identity via getRoleList().

9. Guest fallback

10. If no base roles are resolved, guest is added as the sole identity role.

11. Inherited roles

12. All roles implied by inheritance rules are automatically added.

The returned array is keyed by role name and contains instantiated ACL Role objects, ensuring uniqueness and preventing duplicate role registration.

Parameters:

Return Value:

Map of role name to ACL Role instance representing the complete effective ACL role set.

__construct

Construct the object and initialize its options.

public __construct(array<string,mixed>|null $options = null): mixed

Parameters:

initializeOptions

Capture defaults, apply the current options, and run initialize().

public initializeOptions(array<string,mixed>|null $options = null): void

Parameters:

initialize

Optional hook called after options are initialized.

public initialize(): void

Override this in classes that need to derive internal state from options during construction.

setOptions

Replace or merge the current option set.

public setOptions(array<string,mixed> $options, bool $merge = false): void

Options intentionally use PHP's null-coalescing read semantics: a key stored with a null value remains present in the raw option array, but

• See: \PhalconKit\Support\Options\getOption() returns the caller default and
• See: \PhalconKit\Support\Options\hasOption() reports false for that key.

Parameters:

getOptions

Return the current option set.

public getOptions(): array<string,mixed>

setOption

Store or replace one option value.

public setOption(string $key, mixed $value = null, bool $merge = false): void

Passing null stores the key in the raw option array, but the key still reads as missing through

• See: \PhalconKit\Support\Options\getOption() and
• See: \PhalconKit\Support\Options\hasOption(). This preserves the historical contract where null means "fall back to the caller default" while still allowing callers to inspect raw options.

Parameters:

getOption

Return one option value or a default when it is missing or null.

public getOption(string $key, mixed $default = null): mixed

Parameters:

hasOption

Return true when an option is present and not null.

public hasOption(string $key): bool

This intentionally mirrors

• See: \PhalconKit\Support\Options\getOption() rather than array_key_exists(): null-valued options are stored in the raw option array but are treated as absent by the public lookup helpers.

Parameters:

removeOption

Remove one option key when it exists in the raw option array.

public removeOption(string $key): void

Removal uses array_key_exists() instead of isset() so callers can delete a key even when it currently stores null.

Parameters:

resetOptions

Restore current options to the initialized defaults.

public resetOptions(): void

clearOptions

Remove all current option values.

public clearOptions(): void