README

A library for storing sessions in a database or in cookies, used in the ATK14 Framework.

Installation

composer require atk14/session-storer

Basic usage

$session = new SessionStorer();

$session->writeValue("user_id", 42);
$user_id = $session->readValue("user_id"); // 42

Available options

The constructor accepts an optional array of options:

$session = new SessionStorer([
    "session_name" => "cart",
    "cookie_only"  => true,
]);

Option	Default	Description
`session_name`	`"session"`	Name used for the session cookie
`section`	`"default"`	Logical scope within the session; different sections share the cookie but not keys
`cookie_only`	`false`	Store all values in cookies only, never in the database
`disable_check_cookie`	`false`	Skip the check cookie that detects whether the client accepts cookies
`cookie_expiration`	`0`	Cookie lifetime in seconds (`0` = until browser is closed)
`max_lifetime`	auto	Session lifetime in seconds for garbage collection; derived from `cookie_expiration` if not set

Cookie-only mode

When a database is not available or not desired, values can be stored exclusively in cookies by passing cookie_only => true. The data never touches the database.

$session = new SessionStorer([
    "session_name" => "cart",
    "cookie_only" => true,
]);

$session->writeValue("step", 2);
$step = $session->readValue("step"); // 2

Values are packed into one or more numbered cookies (cart0, cart1, …); the first cookie carries a length prefix separated by a dash (e.g. 1234-<data>). The packed data is encrypted and signed via Packer::Pack(), making it resistant to tampering by the client. Expired values are automatically removed from cookies on the next read.

By default, SessionStorer sends a separate check cookie to detect whether the client has cookies enabled. This can be suppressed with disable_check_cookie => true — useful when you know cookies are supported because another cookie is already being set elsewhere:

$session = new SessionStorer([
    "disable_check_cookie" => true,
]);

Sessions cleanup (cron job)

Old sessions can be cleaned up by calling the static method DeleteOldSessions(). It is suitable for use in a cron job (e.g. sessions_cleanup running once a day):

$deleted = SessionStorer::DeleteOldSessions([
    "session_name" => "session",
    "max_lifetime" => 60 * 60 * 24, // 1 day
]);

Available options for DeleteOldSessions():

Option	Default	Description
`dbmole`	auto	dbmole instance; auto-detected from globals or singleton if not provided
`current_time`	`time()`	Unix timestamp to use as "now"
`session_name`	`null`	if set together with `max_lifetime`, deletes expired sessions by name
`max_lifetime`	`null`	session lifetime in seconds
`deep_clean`	`true`	if true, also deletes all sessions older than 2 years

The method returns the total count of deleted records.

License

MIT

atk14 / session-storer

Maintainers

Package info

Statistics

Security