PHPSession

Native PHP session-backed authentication state backend.

class PHPSession implements \Hazaar\Auth\Interface\SessionBackend

Implements: Hazaar\Auth\Interface\SessionBackend

Implements Hazaar\Auth\Interface\SessionBackend by storing auth identity and payload data under $_SESSION, with values namespaced by Hazaar\Auth\Session\Backend\PHPSession::sessionKey.

Session validity checks include:

• presence of identity and auth payload
• non-empty session payload
• client fingerprint comparison using user-agent and remote IP values

This backend does not support refresh-token rotation and relies on PHP session lifecycle/GC behavior configured at runtime.

Properties

config

private Options $config

Type: Hazaar\Auth\Session\Backend\PHPSession\Options

token

public ExpiringToken $token

Type: Hazaar\Auth\ExpiringToken

refreshToken

public ExpiringToken $refreshToken

Type: Hazaar\Auth\ExpiringToken

Methods

__construct

Constructor for the PHPSession backend.

public __construct(array|Options $config): void

If a session name is specified in the config, it sets the session name.

Parameters

Parameter	Type	Description
$config	array	Hazaar\Auth\Session\Backend\PHPSession\Options

isEmpty

Indicates whether there is a valid authenticated session in memory.

public isEmpty(): bool

Returns: bool

A session is considered empty/invalid when required identity/payload data is missing or client fingerprint checks (user agent/IP) do not match.

read

Reads and returns the session data associated with the current session key.

public read(): array

Returns: array

has

Checks if a specific key exists in the current session.

public has(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the session key to check for existence

get

Retrieves a value from the session using the specified key.

public get(string $key): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$key	string	the key associated with the session value to retrieve

set

Sets a key/value pair in the auth session payload namespace.

public set(string $key, mixed $value): void

Returns: void

Parameters

Parameter	Type	Description
$key	string	session payload key
$value	mixed	value to store

Unsets a value from the session data associated with the given key.

public (string $key): void

Returns: void

Parameters

Parameter	Type	Description
$key	string	the key of the session variable to unset

clear

Clears all authentication-related session state and destroys the PHP session.

public clear(): void

Returns: void

reset

Resets in-memory session state without destroying the persisted PHP session.

public reset(): void

Returns: void

This backend stores its state in the $_SESSION superglobal rather than on the instance, and session_start() does not clear pre-existing $_SESSION keys before merging in stored data. That means a reused backend instance (e.g. an authentication adapter singleton reused across requests under FrankenPHP worker mode) can leak a previous request's session data via $_SESSION even if the instance itself holds no state. Flush and clear the superglobal so the next load()/create() call starts from a clean slate, without calling session_destroy() (that would delete the still-valid persisted session).

getToken

Retrieves the current PHP session ID token.

public getToken(): ?ExpiringToken

Returns: Hazaar\Auth\ExpiringToken

getRefreshToken

Retrieves the refresh token associated with the session.

public getRefreshToken(): ?ExpiringToken

Returns: Hazaar\Auth\ExpiringToken

create

Creates a new session entry with the provided identity and data.

public create(string $identity, array $data): ExpiringToken

Returns: Hazaar\Auth\ExpiringToken

Parameters

Parameter	Type	Description
$identity	string	the identity associated with the session
$data	array

assumeIdentity

Establishes in-memory identity/data without starting or writing a persisted PHP session.

public assumeIdentity(string $identity, array $data): void

Returns: void

Unlike Hazaar\Auth\Session\Backend\PHPSession::create, this never calls Hazaar\Auth\Session\Backend\PHPSession::sessionStart — no session ID is generated and nothing is persisted (no session file, no cookie). It writes directly into the $_SESSION superglobal, which PHP allows even with no active session; those values simply vanish at the end of the request since they were never backed by a started session. Hazaar\Auth\Session\Backend\PHPSession::getToken continues to return null afterwards, since no token was issued.

Parameters

Parameter	Type	Description
$identity	string
$data	array

load

Loads session data for the given token.

public load(string $token, ?array $sessionData, string $tokenType = 'access', ?string $passphrase): bool

Returns: bool

Attempts to set the session ID to the provided token and starts the session with specific options. If a timeout is configured, it sets the session garbage collection max lifetime accordingly. On successful session start, retrieves the session data for the configured session key.

Parameters

Parameter	Type	Description
$token	string	the session token to load
$sessionData	array
$tokenType	string
$passphrase	string

refresh

Refreshes the session using the provided token.

public refresh(string $token): bool

Returns: bool

Parameters

Parameter	Type	Description
$token	string	the session refresh token

getIdentity

Retrieves the identity associated with the current session.

public getIdentity(): ?string

Returns: string

sessionStart

Starts the PHP session with custom options.

private sessionStart(?string $sessionId, ?int $expiresIn): bool

Returns: bool

Disables cookie usage and sets session expiration if configured.

Parameters

Parameter	Type	Description
$sessionId	string
$expiresIn	int

generateTokenString

Generates a unique token string for session authentication.

private generateTokenString(string $identity): string

Returns: string

Uses the SHA-256 hashing algorithm on a unique identifier based on the user's identity.

Parameters

Parameter	Type	Description
$identity	string

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:17 +0000