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

Properties

$config  : array<string, 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.
$setByExternal  : bool
It says that the handler object was set with an externally created object.

Methods

__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, 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

$setByExternal

It says that the handler object was set with an externally created object.

protected bool $setByExternal = false

If this is true, the handler object should not be changed or removed (in the close method).

Some functions, such as session_regenerate_id, call the close method and then open again!

Methods

__construct()

SessionSaveHandler constructor.

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

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

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

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.

setFingerprint()

Set the data fingerprint.

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

The data to set the new fingerprint

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 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results