README

• inanepain/session
• 1. Introduction
  • 1.1. Why SessionManager?
• 2. Install
• 3. Quick Start
  • 3.1. Basic Usage
  • 3.2. Namespaced Sessions
• 4. Configuration
• 5. API Reference
  • 5.1. Initialization
  • 5.2. Core Storage
  • 5.3. Namespacing
  • 5.4. Flash Messages
  • 5.5. Security & Lifecycle
  • 5.6. Remember Me
• 6. Examples
  • 6.1. Login with Remember Me
  • 6.2. Namespaced E-Commerce
• 7. Security Considerations

inanepain/session

A lightweight, secure and extensible PHP session handling library.

1. Introduction

SessionManager is a lightweight, secure, and extensible PHP session handling library designed for modern web applications. It provides a simple static API for managing sessions with built-in security features like HTTP-only cookies, SameSite protection, periodic ID regeneration, and inactivity timeouts. It supports namespacing to avoid key collisions and "remember me" functionality for persistent sessions across browser closes.

Key features: * Automatic secure session initialization. * Namespaced storage to organize data (e.g., user, cart). * Flash messages for one-time notifications. * Configurable timeouts and regeneration intervals. * Memory-safe handling for large sessions. * Persistent sessions via "remember me" (30-day default).

This library is dependency-free, PSR-compliant, and production-ready.

1.1. Why SessionManager?

Native PHP sessions are powerful but lack secure defaults and organization. SessionManager wraps session_* functions with best practices, preventing common pitfalls like fixation attacks and key conflicts.

2. Install

composer require inanepain/session

3. Quick Start

3.1. Basic Usage

Require the file and initialize:

SessionManager::init([
    'name' => 'MYAPP_SESSID',
    // 'cookie_secure' => true,  // HTTPS only
    'cookie_samesite' => 'Strict',
]);

// Set and get data
SessionManager::set('user_id', 123);
echo SessionManager::get('user_id');  // 123

// Flash message
SessionManager::flash('success', 'Login successful!');
header('Location: /dashboard');
exit;

// In dashboard.php
if (SessionManager::hasFlash('success')) {
    echo SessionManager::getFlash('success');
}

// Logout
SessionManager::destroy();

3.2. Namespaced Sessions

Use the base class SessionNamespace for modular access:

class UserSession extends SessionNamespace
{
    protected const NAMESPACE = 'user';
}

class CartSession extends SessionNamespace
{
    protected const NAMESPACE = 'cart';
}

// Usage
UserSession::set('id', 456);
CartSession::set('items', ['item1']);
echo UserSession::get('id');  // 456

4. Configuration

Pass options to init() to customize behaviour. Defaults are secure.

Example with persistent session:

SessionManager::init([
    'remember_me' => true,  // 30-day cookie
    // 'cookie_secure' => true,
]);

Runtime toggles:

SessionManager::enableRememberMe(86400 * 7);  // 1 week
SessionManager::disableRememberMe();  // Back to session-only
echo SessionManager::isRememberMe() ? 'Persistent' : 'Temporary';

5. API Reference

All methods are static. Call init() first.

5.1. Initialization

5.2. Core Storage

5.3. Namespacing

5.4. Flash Messages

5.5. Security & Lifecycle

5.6. Remember Me

6. Examples

6.1. Login with Remember Me

SessionManager::init(['remember_me' => $_POST['remember'] ?? false]);

if (authenticate($_POST['email'], $_POST['password'])) {
    SessionManager::set('user_id', $user->id);
    SessionManager::enableRememberMe();  // If checkbox checked
    SessionManager::flash('success', 'Welcome!');
    header('Location: /dashboard');
} else {
    SessionManager::flash('error', 'Invalid credentials');
}

6.2. Namespaced E-Commerce

UserSession::set('logged_in', true);
CartSession::set('total', 99.99);
echo CartSession::all();  // ['total' => 99.99]
SessionManager::namespace('user');  // Switch back

7. Security Considerations

• Defaults: HTTP-only, SameSite=Lax, strict mode enabled.

• Regeneration: Auto every 10min; manual via regenerate().

• Timeouts: 30min inactivity → auto-destroy.

• Persistent Sessions: Use secure cookies; validate user on resume (e.g., DB token).

• Large Data: Avoid storing files/objects; use DB/Redis for >1MB.

• File Handler: Auto-clears oversized/corrupt sessions; consider Redis for scale.