Aplus Framework Docs

DatabaseHandler extends SaveHandler
in package

Class DatabaseHandler.

CREATE TABLE `Sessions` (
    `id` varchar(128) NOT NULL,
    `timestamp` timestamp NOT NULL,
    `data` blob NOT NULL,
    `ip` varchar(45) NOT NULL, -- optional
    `ua` varchar(255) NOT NULL, -- optional
    PRIMARY KEY (`id`),
    KEY `timestamp` (`timestamp`),
    KEY `ip` (`ip`), -- optional
    KEY `ua` (`ua`) -- optional
);

NOTE: As of PHP 8.4 the id column can be char(32).

Table of Contents

$config  : array<string|int, mixed>
The configurations used by the save handler.
$database  : Database|null
$fingerprint  : string
The current data fingerprint.
$lockId  : false|string
The lock id or false if is not locked.
$logger  : Logger|null
The Logger instance or null if it was not set.
$sessionExists  : bool
Tells if the session exists (if was read).
$sessionId  : string|null
The current session ID.
__construct()  : mixed
SessionSaveHandler constructor.
close()  : bool
Close the session.
destroy()  : bool
Destroy a session.
gc()  : false|int
Cleanup old sessions.
getConfig()  : array<string, mixed>
getDatabase()  : Database|null
open()  : bool
Initialize the session.
read()  : string
Read session data.
setDatabase()  : static
updateTimestamp()  : bool
Update the timestamp of a session.
validateId()  : bool
Validate session id.
write()  : bool
Write session data.
addUserIdColumn()  : void
Adds the optional `user_id` column.
addWhereMatchs()  : void
Adds the `WHERE $column = $value` clauses when matching IP or User-Agent.
getColumn()  : string
Get a column name based on custom/default configs.
getIP()  : string
Get the remote IP address.
getKeySuffix()  : string
getMaxlifetime()  : int
Get the maxlifetime (TTL) used by cache handlers or locking.
getTable()  : string
Get the table name based on custom/default configs.
getUA()  : string
Get the HTTP User-Agent.
hasSameFingerprint()  : bool
Tells if the data has the same current fingerprint.
lock()  : bool
Acquire a lock for a session id.
log()  : void
Log a message if the Logger is set.
prepareConfig()  : void
Prepare configurations to be used by the DatabaseHandler.
setFingerprint()  : void
Set the data fingerprint.
unlock()  : bool
Unlock the current session lock id.
writeInsert()  : bool
writeUpdate()  : bool

Properties

$config

The configurations used by the save handler.

protected array<string|int, mixed> $config

$fingerprint

The current data fingerprint.

protected string $fingerprint

$lockId

The lock id or false if is not locked.

protected false|string $lockId = false

$logger

The Logger instance or null if it was not set.

protected Logger|null $logger

$sessionExists

Tells if the session exists (if was read).

protected bool $sessionExists = false

$sessionId

The current session ID.

protected string|null $sessionId

Methods

__construct()

SessionSaveHandler constructor.

public __construct([array<string, mixed> $config = [] ][, Logger|null $logger = null ]) : mixed
Parameters
$config : array<string, mixed> = []
$logger : Logger|null = null
Return values
mixed —

close()

Close the session.

public close() : bool
Return values
bool —

Returns TRUE on success, FALSE on failure

destroy()

Destroy a session.

public destroy(mixed $id) : bool
Parameters
$id : mixed

The session ID being destroyed

Return values
bool —

Returns TRUE on success, FALSE on failure

gc()

Cleanup old sessions.

public gc(mixed $max_lifetime) : false|int
Parameters
$max_lifetime : mixed

Sessions that have not updated for the last $maxLifetime seconds will be removed

Return values
false|int —

Returns the number of deleted session data for success, false for failure

getConfig()

public getConfig() : array<string, mixed>
Return values
array<string, mixed> —

open()

Initialize the session.

public open(mixed $path, mixed $name) : bool
Parameters
$path : mixed

The path where to store/retrieve the session

$name : mixed

The session name

Return values
bool —

Returns TRUE on success, FALSE on failure

read()

Read session data.

public read(mixed $id) : string
Parameters
$id : mixed

The session id to read data for

Return values
string —

Returns an encoded string of the read data. If nothing was read, it returns an empty string

updateTimestamp()

Update the timestamp of a session.

public updateTimestamp(mixed $id, mixed $data) : bool
Parameters
$id : mixed

The session id

$data : mixed

The encoded session data. This data is the result of the PHP internally encoding the $_SESSION superglobal to a serialized string and passing it as this parameter.

NOTE: Sessions can use an alternative serialization method

Return values
bool —

Returns TRUE on success, FALSE on failure

write()

Write session data.

public write(mixed $id, mixed $data) : bool
Parameters
$id : mixed

The session id

$data : mixed

The encoded session data. This data is the result of the PHP internally encoding the $_SESSION superglobal to a serialized string and passing it as this parameter.

NOTE: Sessions can use an alternative serialization method

Return values
bool —

Returns TRUE on success, FALSE on failure

addUserIdColumn()

Adds the optional `user_id` column.

protected addUserIdColumn(array<string, \Closure|string> &$columns) : void
Parameters
$columns : array<string, \Closure|string>

The statement columns to insert/update

Return values
void —

addWhereMatchs()

Adds the `WHERE $column = $value` clauses when matching IP or User-Agent.

protected addWhereMatchs(Delete|Select|Update $statement) : void
Parameters
$statement : Delete|Select|Update

The statement to add the WHERE clause

Return values
void —

getColumn()

Get a column name based on custom/default configs.

protected getColumn(string $key) : string
Parameters
$key : string

The columns config key

Return values
string —

The column name

getIP()

Get the remote IP address.

protected getIP() : string
Return values
string —

getKeySuffix()

protected getKeySuffix() : string
Return values
string —

getMaxlifetime()

Get the maxlifetime (TTL) used by cache handlers or locking.

protected getMaxlifetime() : int

NOTE: It will use the maxlifetime config or the ini value of session.gc_maxlifetime as fallback.

Return values
int —

The maximum lifetime of a session in seconds

getTable()

Get the table name based on custom/default configs.

protected getTable() : string
Return values
string —

The table name

getUA()

Get the HTTP User-Agent.

protected getUA() : string
Return values
string —

hasSameFingerprint()

Tells if the data has the same current fingerprint.

protected hasSameFingerprint(string $data) : bool
Parameters
$data : string

The data to compare

Return values
bool —

True if the fingerprints are the same, otherwise false

lock()

Acquire a lock for a session id.

protected lock(string $id) : bool
Parameters
$id : string

The session id

Return values
bool —

Returns TRUE on success, FALSE on failure

log()

Log a message if the Logger is set.

protected log(string $message[, LogLevel $level = LogLevel::ERROR ]) : void
Parameters
$message : string

The message to log

$level : LogLevel = LogLevel::ERROR

The log level

Return values
void —

prepareConfig()

Prepare configurations to be used by the DatabaseHandler.

protected prepareConfig(array<string, mixed> $config) : void
Parameters
$config : array<string, mixed>

Custom configs

The custom configs are:

$configs = [
    // The name of the table used for sessions
    'table' => 'Sessions',
    // The maxlifetime used for locking
    'maxlifetime' => null, // Null to use the ini value of session.gc_maxlifetime
    // The custom column names as values
    'columns' => [
        'id' => 'id',
        'data' => 'data',
        'timestamp' => 'timestamp',
        'ip' => 'ip',
        'ua' => 'ua',
    ],
    // Match IP?
    'match_ip' => false,
    // Match User-Agent?
    'match_ua' => false,
    // Independent of match_ip, save the initial IP in the ip column?
    'save_ip' => false,
    // Independent of match_ua, save the initial User-Agent in the ua column?
    'save_ua' => false,
];

NOTE: The Database::connect configs was not shown.

Return values
void —

setFingerprint()

Set the data fingerprint.

protected setFingerprint(string $data) : void
Parameters
$data : string

The data to set the new fingerprint

Return values
void —

unlock()

Unlock the current session lock id.

protected unlock() : bool
Return values
bool —

Returns TRUE on success, FALSE on failure

writeInsert()

protected writeInsert(string $id, string $data) : bool
Parameters
$id : string
$data : string
Return values
bool —

writeUpdate()

protected writeUpdate(string $id, string $data) : bool
Parameters
$id : string
$data : string
Return values
bool —

Search results