class PdoSessionHandler extends AbstractSessionHandler

Session handler using a PDO connection to read and write data.

It works with MySQL, PostgreSQL, Oracle, SQL Server and SQLite and implements different locking strategies to handle concurrent access to the same session. Locking is necessary to prevent loss of data due to race conditions and to keep the session data consistent between read() and write(). With locking, requests for the same session will wait until the other one finished writing. For this reason it's best practice to close a session as early as possible to improve concurrency. PHPs internal files session handler also implements locking.

Attention: Since SQLite does not support row level locks but locks the whole database, it means only one session can be accessed at a time. Even different sessions would wait for another to finish. So saving session in SQLite should only be considered for development or prototypes.

Session data is a binary string that can contain non-printable characters like the null byte. For this reason it must be saved in a binary column in the database like BLOB in MySQL. Saving it in a character column could corrupt the data. You can use createTable() to initialize a correctly defined table.

Constants

LOCK_NONE

No locking is done. This means sessions are prone to loss of data due to race conditions of concurrent requests to the same session. The last session write will win in this case. It might be useful when you implement your own logic to deal with this like an optimistic approach.

LOCK_ADVISORY

Creates an application-level lock on a session. The disadvantage is that the lock is not enforced by the database and thus other, unaware parts of the application could still concurrently modify the session. The advantage is it does not require a transaction.

This mode is not available for SQLite and not yet implemented for oci and sqlsrv.

LOCK_TRANSACTIONAL

Issues a real row lock. Since it uses a transaction between opening and closing a session, you have to be careful when you use same database connection that you also use for your application logic. This mode is the default because it's the only reliable solution across DBMSs.

Methods

open($savePath, $sessionName)

{@inheritdoc}

string
doRead(string $sessionId)

Reads the session data in respect to the different locking strategies.

bool
doWrite(string $sessionId, string $data)

No description

bool
doDestroy(string $sessionId)

No description

validateId($sessionId)

{@inheritdoc}

read($sessionId)

{@inheritdoc}

write($sessionId, $data)

{@inheritdoc}

destroy($sessionId)

{@inheritdoc}

__construct(PDO|string|null $pdoOrDsn = null, array $options = array())

You can either pass an existing database connection as PDO instance or pass a DSN string that will be used to lazy-connect to the database when the session is actually used. Furthermore it's possible to pass null which will then use the session.save_path ini setting as PDO DSN parameter.

createTable()

Creates the table to store sessions which can be called once for setup.

bool
isSessionExpired()

Returns true when the current session exists but expired according to session.gc_maxlifetime.

gc($maxlifetime)

{@inheritdoc}

updateTimestamp($sessionId, $data)

{@inheritdoc}

close()

{@inheritdoc}

PDO
getConnection()

Return a PDO instance.

Details

open($savePath, $sessionName)

{@inheritdoc}

Parameters

$savePath
$sessionName

protected string doRead(string $sessionId)

Reads the session data in respect to the different locking strategies.

We need to make sure we do not return session data that is already considered garbage according to the session.gc_maxlifetime setting because gc() is called after read() and only sometimes.

Parameters

string $sessionId

Return Value

string

protected bool doWrite(string $sessionId, string $data)

Parameters

string $sessionId
string $data

Return Value

bool

protected bool doDestroy(string $sessionId)

Parameters

string $sessionId

Return Value

bool

validateId($sessionId)

{@inheritdoc}

Parameters

$sessionId

read($sessionId)

{@inheritdoc}

Parameters

$sessionId

write($sessionId, $data)

{@inheritdoc}

Parameters

$sessionId
$data

destroy($sessionId)

{@inheritdoc}

Parameters

$sessionId

__construct(PDO|string|null $pdoOrDsn = null, array $options = array())

You can either pass an existing database connection as PDO instance or pass a DSN string that will be used to lazy-connect to the database when the session is actually used. Furthermore it's possible to pass null which will then use the session.save_path ini setting as PDO DSN parameter.

List of available options: * db_table: The name of the table [default: sessions] * db_id_col: The column where to store the session id [default: sess_id] * db_data_col: The column where to store the session data [default: sess_data] * db_lifetime_col: The column where to store the lifetime [default: sess_lifetime] * db_time_col: The column where to store the timestamp [default: sess_time] * db_username: The username when lazy-connect [default: ''] * db_password: The password when lazy-connect [default: ''] * db_connection_options: An array of driver-specific connection options [default: array()] * lock_mode: The strategy for locking, see constants [default: LOCK_TRANSACTIONAL]

Parameters

PDO|string|null $pdoOrDsn A \PDO instance or DSN string or URL string or null
array $options An associative array of options

Exceptions

InvalidArgumentException When PDO error mode is not PDO::ERRMODE_EXCEPTION

createTable()

Creates the table to store sessions which can be called once for setup.

Session ID is saved in a column of maximum length 128 because that is enough even for a 512 bit configured session.hash_function like Whirlpool. Session data is saved in a BLOB. One could also use a shorter inlined varbinary column if one was sure the data fits into it.

Exceptions

PDOException When the table already exists
DomainException When an unsupported PDO driver is used

bool isSessionExpired()

Returns true when the current session exists but expired according to session.gc_maxlifetime.

Can be used to distinguish between a new session and one that expired due to inactivity.

Return Value

bool Whether current session expired

gc($maxlifetime)

{@inheritdoc}

Parameters

$maxlifetime

updateTimestamp($sessionId, $data)

{@inheritdoc}

Parameters

$sessionId
$data

close()

{@inheritdoc}

protected PDO getConnection()

Return a PDO instance.

Return Value

PDO