README

This library provides a flexible, framework-agnostic session management system for PHP.
It is designed as a replacement or alternative to PHP’s built-in $_SESSION handling, while keeping the same conceptual model of key/value session storage.

Key Features

• Interface-driven design: The SessionRegistry interface defines a consistent contract for session handling, making it easy to plug in different storage backends.
• Multiple implementations:
  • VolatileSessionRegistry – in-memory sessions that only last for the duration of a request (no persistence).
  • FileSessionRegistry – file-based sessions, compatible with PHP’s default behavior but with more control and extensibility.
  • StreamSessionRegistry – stream-backed sessions (useful for custom storage like memory streams, sockets, or database-backed streams).
• BaseSessionRegistry: Provides shared logic for managing session key/value pairs, reducing duplication in implementations.
• Custom session IDs: Sessions use secure, random identifiers (base64url-encoded) that can be customized or replaced.

Why use this?

PHP’s built-in session handling is tightly coupled to files and the global $_SESSION superglobal.
This library decouples session logic from storage, allowing you to integrate sessions into more advanced architectures:

• Store session data in files, memory, or streams.
• Run without touching $_SESSION.
• Implement custom storage (Redis, databases, etc.) by extending BaseSessionRegistry.

Example Usage

use gabbro\auth\FileSessionRegistry;

// Create a file-backed session
$session = new FileSessionRegistry();

// Set some data
$session->set("user_id", 123);

// Retrieve data
$userId = $session->get("user_id");

// Save to storage
$session->save();

Garbage Collection

File-based sessions include lightweight garbage collection, triggered randomly during construction, to clean up expired session files. This mimics PHP’s native behavior but gives you more explicit control.

Extensibility

The library is designed to be extended. You can easily create your own session registry by extending BaseSessionRegistry and implementing save().

For example, you could implement a DatabaseSessionRegistry that stores serialized session data in a database table.