omatamix / session-lock

v5.0.1 2020-09-12 12:10 UTC

Requires

• php: >=7.3
• cakephp/database: ^4.1
• defuse/php-encryption: ^2.2
• symfony/cache: ^5.1
• symfony/filesystem: ^5.1
• symfony/options-resolver: ^5.1
• symfony/polyfill-apcu: ^1.18
• symfony/polyfill-ctype: ^1.18

Requires (Dev)

• phpunit/phpunit: ^9

MIT

Published on Packagist.org on 2020-09-13 09:19 UTC

README

Secure, framework-agnostic PHP session management.

What's new in this modernization

• PHP 8.2+ and modern dependencies
• Fixed fingerprint comparison bug
• Fixed methods that declared bool but returned nothing
• CLI-compatible session status for automated tests
• Dot-notation session keys
• pull, only, replace, increment, and decrement
• TTL session values
• Laravel-style flash lifecycle: flash, now, keep, reflash
• CSRF token generation/validation
• Automatic session ID rotation
• Session metadata
• Safer defaults: strict mode, HttpOnly, SameSite=Lax
• User-agent fingerprinting by default; IP binding is opt-in to reduce false positives
• Dependency-injectable fingerprint provider
• Lazy session start option
• Framework-agnostic middleware
• In-memory, cache, and null session handlers
• Backward-compatible aliases: stopSession, regenerateSessionID, and historical regerate
• PHPUnit + GitHub Actions matrix

Install

composer require omatamix/session-lock

Basic usage

use Omatamix\SessionLock\SessionManager;

$session = new SessionManager();
$session->start();

$session->put('user.name', 'Nick');
echo $session->get('user.name');

$session->forget('user.name');

TTL values

$session->put('password_confirmed', true, ttlSeconds: 300);

Flash data

$session->flash('status', 'Profile updated.');

The value survives the current request and one subsequent session start. Use keep() or reflash() to preserve it for another request.

CSRF

$token = $session->csrfToken();

if (!$session->validateCsrfToken($_POST['_token'] ?? null)) {
    http_response_code(419);
    exit('Invalid CSRF token');
}

Fingerprinting

$session = new SessionManager([
    'fingerprinting' => true,
    'bind_user_agent' => true,
    'bind_ip_address' => false,
]);

IP binding is deliberately opt-in. Mobile networks, proxies, VPNs, and IPv6 privacy addresses can change a legitimate user's IP during a session.

Automatic ID rotation

$session = new SessionManager([
    'auto_regenerate_seconds' => 900,
]);

Always regenerate after login, privilege elevation, or other authentication boundary:

$session->regenerate();

Cache handler

use Omatamix\SessionLock\SessionHandlers\CacheSessionHandler;

$session->setSaveHandler(new CacheSessionHandler($psr16Cache, ttl: 3600));

Security notes

• Fingerprinting is a defense-in-depth signal, not identity proof.
• Use TLS in production.
• Regenerate the session ID after authentication.
• Keep session.use_strict_mode enabled.
• Prefer Secure, HttpOnly, and an appropriate SameSite cookie policy.
• Do not store secrets in a client-readable cookie session handler unless the contents are authenticated and encrypted.

Compatibility

PHP 8.2, 8.3, 8.4.

License

MIT.