README

Secure PHP session handler with advanced security features and session management.

Features

Secure session configuration out of the box
Session timeout management (idle timeout)
Session integrity checks (IP and User-Agent validation)
Protection against session fixation attacks
Strict session management
Cookie security controls
Session status monitoring

Requirements

PHP 8.1 or higher

Installation

composer require solophp/session

Basic Usage

use Solo\Session\Session;

// Create session with default secure settings
$session = new Session();

// Store data
$session->set('user', $userData);

// Get data
$userData = $session->get('user');

// Check if data exists
if ($session->has('user')) {
    // ...
}

// Remove data
$session->unset('user');

// Clear all data
$session->clear();

// Completely destroy session
$session->destroy();

Configuration

$session = new Session(
    lifetime: 1800,          // Idle timeout in seconds (default: 1800 = 30 minutes)
    expireOnClose: true,     // Delete session cookie when browser closes (default: true)
    secure: true,            // Require HTTPS (default: true)
    httpOnly: true,          // Prevent JavaScript access (default: true)
    sameSite: 'Strict',      // CSRF protection: 'Strict'|'Lax'|'None' (default: 'Strict')
    path: '/',               // Cookie path (default: '/')
    domain: '',              // Cookie domain (default: '')
    useStrictMode: true,     // Enable strict mode (default: true)
    useCookiesOnly: true     // Prevent session ID in URLs (default: true)
);

Configuration Options

Parameter	Type	Default	Description
`lifetime`	int	1800	Idle timeout in seconds. Session expires after this period of inactivity.
`expireOnClose`	bool	true	If true, session cookie is deleted when browser closes. If false, cookie persists for `lifetime` seconds.
`secure`	bool	true	Only send cookie over HTTPS.
`httpOnly`	bool	true	Prevent JavaScript access to session cookie.
`sameSite`	string	'Strict'	CSRF protection level: 'Strict', 'Lax', or 'None'.
`path`	string	'/'	Cookie path.
`domain`	string	''	Cookie domain.
`useStrictMode`	bool	true	Reject uninitialized session IDs.
`useCookiesOnly`	bool	true	Prevent session ID from being passed via URL.

Security Features

Session Timeout

Sessions automatically expire after a period of inactivity (default 30 minutes):

// Check if session has expired
if ($session->isExpired()) {
    // Handle expired session
}

// Get last activity timestamp
$lastActivity = $session->getLastActivity();

// Get session creation timestamp
$createdAt = $session->getCreatedAt();

Session Integrity

Sessions are validated against:

User's IP address
User's browser (User-Agent)
Session initiation status

Cookie Security

Secure cookie settings:

HttpOnly flag
Secure flag (HTTPS only)
SameSite attribute
Configurable domain and path
Optional expiration on browser close

Available Methods

Data Management

// Get value with default fallback
$value = $session->get('key', 'default');

// Set value
$session->set('key', 'value');

// Check existence
$exists = $session->has('key');

// Remove specific key
$session->unset('key');

// Get all session data
$allData = $session->all();

// Clear all data
$session->clear();

Session Management

// Regenerate session ID
$session->regenerateId();

// Destroy session completely
$session->destroy();

// Get current session ID
$id = $session->getCurrentId();

// Get session cookie name
$name = $session->getCookieName();

// Get session save path
$path = $session->getSavePath();

// Get session status
$status = $session->getStatus();

// Get configured lifetime
$lifetime = $session->getLifetime();

// Get session creation time
$createdAt = $session->getCreatedAt();

Session Status Values

PHP_SESSION_DISABLED = 0
PHP_SESSION_NONE = 1
PHP_SESSION_ACTIVE = 2

Development

Running Tests

composer test

Static Analysis

composer analyse

Code Style

Check code style:

composer cs-check

Fix code style:

composer cs-fix

Run All Quality Checks

composer quality

Best Practices

Always use HTTPS in production (secure: true)
Set appropriate lifetime values for your application
Consider using 'Strict' SameSite setting for better security
Monitor session activity using provided methods
Handle expired sessions appropriately
Use session regeneration for sensitive operations

License

MIT

solophp / session

Maintainers

Details