Adapter

Abstract authentication adapter.

class Adapter implements \Hazaar\Auth\Interface\AuthenticationAdapter , \ArrayAccess

Implements: Hazaar\Auth\Interface\AuthenticationAdapter, ArrayAccess

This class is the base class for all of the supplied authentication adapters. This class takes care of the password hash generation and session management, including the autologin function.

Runtime responsibilities include adapter instance lifecycle management, identity/credential verification, backend session state handling, and token transport persistence on outgoing responses.

See Hazaar\Auth\Adapter\Options for the available configuration options.

Properties

backend

Session backend implementation used for auth state storage.

public SessionBackend $backend

Type: Hazaar\Auth\Interface\SessionBackend

transport

Session transport implementation responsible for token persistence.

public SessionTransport $transport

Type: Hazaar\Auth\Interface\SessionTransport

options

The configuration options.

protected Options $options

Type: Hazaar\Auth\Adapter\Options

identity

public string $identity

Type: string

credential

public string $credential

Type: string

noCredentialHashing

Controls whether credential hashing is bypassed during verification.

private bool $noCredentialHashing

Type: bool

instances

Instances of adapters.

private array $instances

Type: array

commitChanges

private bool $commitChanges

Type: bool

Methods

__construct

Construct the adapter.

public __construct(Options $options = 'new Options()'): void

Parameters

Parameter	Type	Description
$options	Hazaar\Auth\Adapter\Options

getInstance

Returns an instance of the specified authentication adapter.

public getInstance(?array $config): Adapter

Returns: Hazaar\Auth\Adapter

If no configuration array is provided, it loads the configuration from the default source. Throws an InvalidArgumentException if the adapter is not specified or the class does not exist. Caches adapter instances for reuse.

Parameters

Parameter	Type	Description
$config	array

setIdentity

Sets the identity for the authentication adapter.

public setIdentity(string $identity): void

Returns: void

Parameters

Parameter	Type	Description
$identity	string	the identity to be set

getCredentialHash

Get the encrypted hash of a credential/password.

public getCredentialHash(?string $credential): ?string

Returns: string

This method uses the "encryption" options from the application configuration to generate a password hash based on the supplied password. If no password is supplied then the currently set credential is used.

NOTE: Keep in mind that if no credential is set, or it's null, or an empty string, this will still return a valid hash of that empty value using the defined encryption hash chain.

Parameters

Parameter	Type	Description
$credential	string

authenticate

Attempts to authenticate a user using the provided identity and credential.

public authenticate(?string $identity, ?string $credential): Result

Returns: Hazaar\Auth\Result

This method performs the following steps:

1. Trims and validates the provided identity and credential.
2. Queries the authentication source for user data using the identity.
3. Verifies that the returned data contains both 'identity' and 'credential' fields.
4. Compares the provided identity and hashed credential with the stored values using a timing-safe comparison.
5. On success, creates a session for the user and calls authenticationSuccess().
6. On failure, clears any existing session and calls authenticationFailure().

Parameters

Parameter	Type	Description
$identity	string	The identity of the user (e.g., username, email). If null, defaults to an empty string.
$credential	string	The credential of the user (e.g., password). If null, defaults to an empty string.

refresh

public refresh(?string $token): Result

Returns: Hazaar\Auth\Result

Parameters

Parameter	Type	Description
$token	string

authenticated

Checks if the user is authenticated.

public authenticated(): bool

Returns: bool

This method verifies if the storage is not empty and contains an 'identity' key. If the storage is empty or does not have the 'identity' key, it clears the storage and returns false. Otherwise, it returns true indicating the user is authenticated.

getToken

Retrieves the authentication token from the backend.

public getToken(): ?ExpiringToken

Returns: Hazaar\Auth\ExpiringToken

getRefreshToken

Retrieves the refresh token from the backend.

public getRefreshToken(): ?ExpiringToken

Returns: Hazaar\Auth\ExpiringToken

revokeRefreshToken

Revokes a single refresh token outright (e.g. on logout), without rotating it.

public revokeRefreshToken(string $token): bool

Returns: bool

A no-op that returns false if the configured backend's refresh tokens aren't revocable (i.e. it doesn't implement Hazaar\Auth\Interface\RevocableSessionBackend) — a caller that wants to be sure revocation actually happened should check the return value.

Parameters

Parameter	Type	Description
$token	string

revokeAllSessions

Revokes every outstanding refresh token for the currently authenticated identity (e.g. on

public revokeAllSessions(): bool

Returns: bool

password change, or an explicit "log out of all other sessions" action).

Reads the identity from the backend (not the adapter's own Hazaar\Auth\Adapter::identity property, which is only ever populated by Hazaar\Auth\Adapter::authenticate/Hazaar\Auth\Adapter::refresh — a request authenticated via middleware calling Hazaar\Auth\Interface\SessionBackend::load directly never sets it). A no-op that returns false if there's no authenticated identity, or the configured backend's refresh tokens aren't revocable.

listDevices

Lists every outstanding device/session for the currently authenticated identity, e.g. for

public listDevices(): array

Returns: array

a "you're logged in on these devices" UI.

Reads the identity from the backend, the same as Hazaar\Auth\Adapter::revokeAllSessions does, for the same reason. Returns an empty array if there's no authenticated identity, or the configured backend doesn't support device listing.

revokeDevice

Revokes a single device/session outright (e.g. "log out this device") for the currently

public revokeDevice(string $sessionId): bool

Returns: bool

authenticated identity.

A no-op that returns false if there's no authenticated identity, or the configured backend doesn't support device listing.

Parameters

Parameter	Type	Description
$sessionId	string

check

Check that the supplied password is correct for the current identity.

public check(string $identity, string $credential): bool

Returns: bool

This is useful for checking an account password before allowing something important to be updated. This does the same steps as authenticate() but doesn't actually do the authentication.

Parameters

Parameter	Type	Description
$identity	string
$credential	string

persistenceMode

Returns the persistence mode of the configured transport.

public persistenceMode(): TransportPersistence

Returns: Hazaar\Auth\Enum\TransportPersistence

Controllers can use this to decide whether to include token data in the response body (ClientManaged) or rely on automatic cookie handling (ServerManaged).

if ($auth->persistenceMode() === TransportPersistence::ClientManaged) {
    return new JSON($result->token);
}
return new Response('text/html', 200);

resetState

Resets all per-request state on this adapter instance.

public resetState(): void

Returns: void

Unlike Hazaar\Auth\Adapter::clear, this does not log the user out or destroy any persisted session/token — it only drops in-memory state (identity, credential, pending commit flag, and the backend's own in-memory state via Hazaar\Auth\Interface\SessionBackend::reset).

This must be called at the end of every request that used this adapter, so that a long-lived adapter instance (e.g. resolved once via Hazaar\Auth\Adapter::getInstance and reused across requests, such as under FrankenPHP worker mode) never leaks one request's identity/session data into the next.

authenticateAs

Establishes an authenticated session for an identity verified by some other means.

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

Returns: void

Use this when the caller has already verified the identity through a channel other than a session token — for example, validating an API key against another service — and wants to mark the current request as authenticated for that identity. No token is generated or signed and nothing is persisted: the identity/data are set in memory for the current request only, backed by Hazaar\Auth\Interface\SessionBackend::assumeIdentity.

Because no signing occurs, this works even on a verify-only adapter/backend that has no private key configured (e.g. a service that only ever validates tokens issued elsewhere).

Parameters

Parameter	Type	Description
$identity	string	the identity to establish for the current request
$data	array

clear

Clears the current authentication session from the backend.

public clear(): bool

Returns: bool

Instructs the backend to destroy all session state for the current identity and schedules a transport commit so that any persisted tokens (e.g. cookies or advisory headers) are cleared from the client on the next response.

unauthorised

Helper method that sets the basic auth header and throws an unauthorised exception.

public unauthorised(): void

Returns: void

disableCredentialHashing

Toggles on/off the internal credential hashing algorithm.

public disableCredentialHashing(bool $value = true): void

Returns: void

This is useful is you want to authenticate with an already hashed credential.

WARNING: This should NOT normally be used. And if it IS used, it should only be used to authenticate credentials supplied internally by the application itself, and not provided by a user/client/etc. Disabling password hash essentially turns this all into clear text credentials.

Parameters

Parameter	Type	Description
$value	bool

toArray

Converts the authentication adapter data to an array.

public toArray(): array

Returns: array

This method retrieves and returns the data from the backend as an array.

get

Retrieves a value from the storage based on the provided key.

public get(string $key): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$key	string	the key used to retrieve the value from the storage

set

Sets a value in the storage with the specified key.

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

Returns: void

Parameters

Parameter	Type	Description
$key	string	the key under which the value will be stored
$value	mixed	the value to be stored

has

Checks if a given key exists in the storage.

public has(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to check for existence in the storage

public (string $key): void

Returns: void

Parameters

Parameter	Type	Description
$key	string

offsetExists

public offsetExists(mixed $offset): bool

Returns: bool

Parameters

Parameter	Type	Description
$offset	mixed

offsetGet

public offsetGet(mixed $offset): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$offset	mixed

offsetSet

public offsetSet(mixed $offset, mixed $value): void

Returns: void

Parameters

Parameter	Type	Description
$offset	mixed
$value	mixed

offsetUnset

public offsetUnset(mixed $offset): void

Returns: void

Parameters

Parameter	Type	Description
$offset	mixed

getSessionData

Retrieves session data from the backend storage.

public getSessionData(): array

Returns: array

setSessionBackend

Sets the storage adapter for authentication.

public setSessionBackend(SessionBackend|string $backend, array $options): bool

Returns: bool

Parameters

Parameter	Type	Description
$backend	Hazaar\Auth\Interface\SessionBackend	string
$options	array	optional configuration options for the storage adapter

setSessionTransport

Sets the session transport mechanism for authentication.

public setSessionTransport(SessionTransport|string $transport, array $options): bool

Returns: bool

Parameters

Parameter	Type	Description
$transport	Hazaar\Auth\Interface\SessionTransport	string
$options	array	optional configuration options to pass to the transport backend

commit

Commits the authentication token to the response if available.

public commit(Response $response): void

Returns: void

Retrieves the authentication token from the backend. If a token exists, it persists the token using the transport mechanism into the provided response.

Parameters

Parameter	Type	Description
$response	Hazaar\Controller\Response	the response object to which the token should be persisted

getIdentifier

Generates a hashed identifier for the given identity string.

protected getIdentifier(string $identity): ?string

Returns: string

This method takes an identity string and returns its SHA-1 hash. If the identity string is empty or null, the method returns null.

Parameters

Parameter	Type	Description
$identity	string	the identity string to be hashed

authenticationSuccess

Overload function called when a user is successfully authenticated.

protected authenticationSuccess(string $identity, array $data): void

Returns: void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters

Parameter	Type	Description
$identity	string	The identity that was successfully authenticated
$data	array	The data returned from the authentication query

authenticationFailure

Overload function called when a user fails authentication.

protected authenticationFailure(string $identity, array $data): void

Returns: void

This can occur when calling authenticate() or authenticated() where a session has been saved. This default method does nothing but can be overridden.

Parameters

Parameter	Type	Description
$identity	string	the identity that failed authentication
$data	array	the data returned from the authentication query

---

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