Session

Stores the lightweight identity payload for the active manager.

By default the payload is written under the active JWT claim key in the configured session service. This allows JWT refreshes to rotate the storage key and invalidate older tokens while preserving the small userId and asUserId payload.

When identity.stateless is enabled, the same payload is stored directly in the JWT claim instead. That mode is intended for API clients that want the identity layer to avoid PHP session persistence while the rest of the application can still use sessions for unrelated features such as flash messages, OAuth2 state, or locale persistence.

• Full name: \PhalconKit\Identity\Traits\Session

Constants

Methods

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.