bayfrontmedia / session-manager
A framework-agnostic PHP library to manage sessions using multiple storage options.
Requires
- php: ^8.0
- ext-pdo: *
- bayfrontmedia/php-array-helpers: ^2.0
- bayfrontmedia/php-cookies: ^2.0
README
A framework-agnostic PHP library to manage sessions using multiple storage options.
License
This project is open source and available under the MIT License.
Author
Requirements
- PHP
^8.0 - PDO PHP extension
Installation
composer require bayfrontmedia/session-manager
Usage
Session handler
A \SessionHandlerInterface must be passed to the Bayfront\SessionManager\Session constructor.
There are a variety of session handlers available, each with their own required configuration.
In addition, you may also create and use your own session handlers to be used with Session Manager.
LocalHandler
The LocalHandler allows you to store sessions in the local filesystem using native PHP.
use Bayfront\SessionManager\Handlers\LocalHandler;
$handler = new LocalHandler('/root_path');
PdoHandler
The PdoHandler allows you to use a PDO instance for session storage in a database.
use Bayfront\SessionManager\Handlers\PdoHandler;
$dbh = new PDO('mysql:host=localhost;dbname=DATABASE_NAME', 'USERNAME', 'PASSWORD');
// Pass the table name to be used in the constructor - "sessions" by default
$handler = new PdoHandler($dbh, 'sessions');
Before using the PdoHandler, the required database table must be created with the up method,
and may throw a Bayfront\SessionManager\HandlerException exception:
try {
$handler->up();
} catch (HandlerException $e) {
die($e->getMessage());
}
Start using Session Manager
Once your handler has been created, it can be used with Session Manager. In addition, a configuration array should be passed to the constructor.
Unless otherwise specified, the default configuration will be used, as shown below:
use Bayfront\SessionManager\Handlers\LocalHandler;
use Bayfront\SessionManager\Session;
$handler = new LocalHandler('/root_path');
$config = [
'cookie_name' => 'bfm_sess',
'cookie_path' => '/',
'cookie_domain' => '',
'cookie_secure' => true,
'cookie_http_only' => true,
'cookie_same_site' => 'Lax', // None, Lax or Strict
'sess_regenerate_duration' => 300, // 0 to disable
'sess_lifetime' => 3600, // 0 for "until the browser is closed"
'sess_gc_probability' => 1, // 0 to disable garbage collection
'sess_gc_divisor' => 100
];
$session = new Session($handler, $config);
The cookie_* keys allow you to configure the session cookie parameters.
The sess_regenerate_duration key is the number of seconds interval before a new session is automatically created (prevents session fixation).
Set to 0 to disable automatically regenerating sessions.
The sess_lifetime key is the number of seconds the session will be valid. Set to 0 for the session to be valid only "until the browser is closed".
The sess_gc_* keys define the probability and divisor for the garbage cleanup.
NOTE: Be sure to call start before using any other methods to ensure the session has begun.
Public methods
- start
- startNew
- regenerate
- destroy
- getId
- getLastActive
- getLastRegenerate
- get
- has
- set
- forget
- flash
- getFlash
- hasFlash
- keepFlash
- reflash
start
Description:
Start a new session.
Parameters:
- None
Returns:
- (self)
Example:
$session->start();
startNew
Description:
Destroy existing and start a new session.
Parameters:
- None
Returns:
- (self)
Example:
$session->startNew();
regenerate
Description:
Regenerate new session ID.
When $delete_old_session = TRUE, the old session file will be deleted.
Parameters:
$delete_old_session = false(bool)
Returns:
- (self)
Example:
$session->regenerate();
destroy
Description:
Destroy the current session file and cookie.
Parameters:
- None
Returns:
- (self)
Example:
$session->destroy();
getId
Description:
Return current session ID
Parameters:
- None
Returns:
- (string)
Example:
echo $session->getId();
getLastActive
Description:
Return the last active time of the session.
Parameters:
- None
Returns:
- (int)
Example:
echo $session->getLastActive();
getLastRegenerate
Description:
Return the last regenerated time of the session.
Parameters:
- None
Returns:
- (int)
Example:
echo $session->getLastRegenerate();
get
Description:
Returns value of single $_SESSION array key in dot notation, or entire array, with optional default value.
Parameters:
$key = NULL(string): Returns the entire array whenNULL$default = NULL(mixed)
Returns:
- (mixed)
Example:
echo $session->get('user.id');
has
Description:
Checks if $_SESSION array key exists in dot notation.
Parameters:
$key(string)
Returns:
- (bool)
Example:
if ($session->has('user.id')) {
// Do something
}
set
Description:
Sets a value for a $_SESSION key in dot notation.
Parameters:
$key(string)$value(mixed)
Returns:
- (self)
Example:
$session->set('user.id', 5);
forget
Description:
Remove a single key, or an array of keys from the $_SESSION array using dot notation.
Parameters:
$keys(string|array)
Returns:
- (self)
Example:
$session->forget('user.id');
flash
Description:
Sets a value for flash data in dot notation.
Flash data is available immediately and during the subsequent request.
Parameters:
$key(string)$value(mixed)
Returns:
- (self)
Example:
$session->flash('status', 'Task was successful');
getFlash
Description:
Returns value of single flash data key in dot notation, or entire array, with optional default value.
Parameters:
$key = NULL(string): Returns the entire flash array whenNULL$default = NULL(mixed)
Returns:
- (self)
Example:
echo $session->getFlash('status');
hasFlash
Description:
Checks if flash data key exists in dot notation.
Parameters:
$key(string)
Returns:
- (bool)
Example:
if ($session->hasFlash('status')) {
// Do something
}
keepFlash
Description:
Keeps specific flash data keys available for the subsequent request.
Parameters:
$keys(array)
Returns:
- (self)
Example:
$session->keepFlash([
'status'
]);
reflash
Description:
Keeps all flash data keys available for the subsequent request.
Parameters:
- None
Returns:
- (self)
Example:
$session->reflash();