PHP Luminova: Database Session Handler

Last updated: 2024-12-27 13:37:54

The DatabaseSessionHandler class enables storing PHP session data in a database, offering enhanced control, security, and scalability compared to default file-based session handling. This handler is particularly useful for applications requiring session data to persist across distributed systems or when integrating with other database-driven features.

Key features include:

Optional Data Encryption: Ensures session data is stored securely, protecting it from unauthorized access.
IP Binding: Ties sessions to client IPs for improved security.
Column Prefixing: Avoids naming conflicts in shared database tables.
Caching Support: Boosts performance by caching session data in memory.
Custom Callbacks: Hooks for session lifecycle events such as validation, creation, and closure.

It extends the SessionHandler class, ensuring backward compatibility with file-based session handling, making it a robust and flexible for managing sessions in PHP.

Usage Example

The following example demonstrates how to configure and use the DatabaseSessionHandler with the Session class to manage sessions in a database.

use Luminova\Sessions\Session;
use Luminova\Sessions\DatabaseSessionHandler;

$session = new Session();
$session->setHandler(new DatabaseSessionHandler('sessions', [
    'encryption'    => true,         // Enable encryption for session data
    'session_ip'    => true,         // Bind sessions to client IPs
    'columnPrefix'  => 'session_',   // Use 'session_' as column prefix
    'cacheable'     => true          // Enable in-memory caching
]));
$session->start();

// Set and retrieve session data
$session->set('foo', 'Hello World');
echo $session->get('foo'); // Outputs: Hello World

Database Table Structure

Below is the suggested table structure for storing session data. It is crucial to ensure that the table is optimized for your database engine and application requirements.

CREATE TABLE `YourSessionsTableName` (
    `id` VARCHAR(255) CHARACTER SET utf8 COLLATE utf8_unicode_ci NOT NULL, -- Unique session identifier
    `data` TEXT NOT NULL,                                                 -- Serialized session data
    `ip` VARBINARY(32) DEFAULT NULL,                                      -- IP address of the client
    `timestamp` INT(11) UNSIGNED NOT NULL,                                -- Last update timestamp
    `lifetime` INT(11) UNSIGNED NOT NULL,                                 -- Session expiration time
    PRIMARY KEY (`id`),
    KEY `timestamp_index` (`timestamp`)                                   -- Index for efficient timestamp queries
) ENGINE=<YourDbEngine> DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

Using Database Migrations

You can create a dedicated migration for your sessions table to fasten database schema management. Below is an example using the Luminova framework's migration blueprint.

// /app/Database/Migrations/SessionsMigration.php

namespace App\Database\Migrations;

use Luminova\Database\Migration;
use Luminova\Database\Table;
use Luminova\Database\Schema;

class SessionsMigration extends Migration
{
    /**
     * Define the schema for the sessions table.
     * 
     * Command to run the migration:
     * php novakit db:migrate --class=SessionsMigration
     */
    public function up(): void
    {
        // Define the sessions table structure
        Schema::create('YourSessionsTableName', function (Table $table) {
            $table->prettify = true;
            $table->collation = 'utf8mb4_unicode_ci'; // Set collation for the table
            $table->charset = 'utf8mb4'; // Set character set

            // Define table columns
            $table->varchar('id', 255)
                ->primary() // Set as primary key
                ->nullable(false) // Column cannot be null
                ->collation('utf8_unicode_ci'); // Set specific collation for the column

            $table->text('data')
                ->nullable(false); // Column cannot be null

            $table->varBinary('ip', 32)
                ->default(null); // IP address column, allows null by default

            $table->integer('timestamp', 11)
                ->unsigned() // Unsigned integer for positive values only
                ->nullable(false) // Column cannot be null
                ->index(Table::INDEX_PRIMARY_KEY); // Add index for efficient lookups

            $table->integer('lifetime', 11)
                ->unsigned() // Unsigned integer
                ->nullable(false); // Column cannot be null

            return $table;
        });
    }

    /**
     * Rollback the migration by dropping the sessions table.
     */
    public function down(): void
    {
        Schema::dropIfExists('YourSessionsTableName');
    }

    public function alter(): void {}
}

Notes: Table Prefixing: If a column prefix is specified (e.g., session_), ensure to update the column names accordingly (e.g., session_id, session_data).

Class Definition

Class namespace: \Luminova\Sessions\DatabaseSessionHandler
Parent class: SessionHandler

Methods

constructor

Constructor to initialize the session handler.

public __construct(string $table, array<string,mixed> $options = []): mixed

Parameters:

Parameter	Type	Description
`$table`	string	The name of the database table for session storage.
`$options`	array<string,mixed>	Configuration options for session handling.

Options

Session Database Handler Options

[
    'encryption'    => false, // Enables encryption for session data to enhance security. 
    'session_ip'    => false, // Binds sessions to the client's IP address to prevent session hijacking.  
    'columnPrefix'  => null, // Specifies a prefix for session-related columns to avoid name conflicts in shared tables.  
    'cacheable'     => true, // Enables in-memory caching for faster session data retrieval.
    'onValidate'    => null, // A callback executed during session validation, useful for custom checks.
    'onCreate'      => null, // A callback triggered upon session creation.  
    'onClose'       => null  // A callback triggered when a session is closed or destroyed. 
]

Configuration Options

This section outlines the available options for configuring a session database handler. These options provide flexibility in managing session data storage and behavior.

encryption (bool)
Enables or disables encryption for session data. When set to true, the session data is encrypted before storage and decrypted upon retrieval. The encryption utilizes the default application encryption configuration based on App\Config\Encryption.Default: false
Example:
```
'encryption' => true
```
session_ip (bool)When enabled, this option ties the session to the IP address of the client, enhancing security by preventing session hijacking from different IPs.
Default: false
Example:
```
'session_ip' => true
```
columnPrefix (string|null)
Specifies a prefix to be added to all session-related database columns. This can help avoid column name collisions in shared database tables.
Default: null
Example:
```
'columnPrefix' => 'user_session_'
```
cacheable (bool)
Determines whether session data should be cached in memory for faster access. When true, caching mechanisms (if available) are utilized.
Default: false
Example:
```
'cacheable' => true
```
onValidate (callable|null)A custom callback function executed during session ID validation. This can be used to perform additional checks, such as validating user-agent strings or custom tokens.
Default: null
Example:
```
'onValidate' => function (string $id, bool $exists): bool {
   // Custom validation logic
   return $exists && doExtraCheck($id);
}
```
onCreate (callable|null)
A custom callback function triggered when a new session is created. This is useful for initializing session-specific resources or logging creation events.
Default: null
Example:
```
'onCreate' => function (string $path, string $name): bool {
   // Logic for new session creation
   return true;
}
```
onClose (callable|null)
A custom callback function triggered when a session is closed or destroyed. This can be used to clean up resources or log session closure events.
Default: null
Example:
```
'onClose' => function (): bool {
   // Logic for session closure
   return true;
}
```

« Previous Session Management

Next » Session Examples

Luminova Framework

Version