Session Laravel Package

Getting Started

Start by installing the package via Composer:

composer require joomla/session "~3.0"

The package requires PHP 8.1+, and provides a clean, object-oriented session API abstracting PHP’s native $_SESSION. Its core classes are Session, StorageInterface, and HandlerInterface. For basic use, inject NativeStorage into a Session instance and call start() explicitly when needed. Unlike legacy approaches, sessions are not auto-started—this gives you precise control over lifecycle and avoids side effects in CLI or testing contexts.

A minimal example:

use Joomla\Session\Session;
use Joomla\Session\Storage\NativeStorage;

$storage = new NativeStorage();
$session = new Session($input, $dispatcher, $storage);
$session->start();

$session->set('user.id', 42);
echo $session->get('user.id'); // 42

Key entry points are the SessionInterface and StorageInterface—design against these interfaces to remain flexible and testable.

Implementation Patterns

• DI Container Integration: Avoid getInstance() (removed in v2). Instead, register SessionInterface as a shared service in your DI container (e.g., in a Laravel service provider: app()->singleton(SessionInterface::class, fn() => new Session($input, $events, new NativeStorage()));).
• Testing with RuntimeStorage: Use RuntimeStorage during unit tests or CLI commands to isolate sessions from real $_SESSION:

  $storage = new RuntimeStorage();
  $session = new Session(new ArrayInput(), $dispatcher, $storage);
  

• CSRF Protection: Leverage getToken() and hasToken() for secure form handling:

  <input type="hidden" name="{{ $session->getToken(true) }}" value="1">
  

  Validate on submit:

  if (!$session->hasToken($token)) {
      abort(403, 'Invalid token');
  }
  

• Event-Driven Flows: Subscribe to onAfterSessionStart/onAfterSessionRestart events (via SessionEvent) to hydrate user context, audit logs, or token rotation.
• Session Forking for Auth: After login, use $session->fork() to migrate session data to a new ID, preventing fixation attacks.

Gotchas and Tips

• No Auto-Start: Sessions must be started manually. Forgetting $session->start() before reading/writing is the most common mistake—expect silent failures or new session IDs on each request.
• Namespace Removal: v2 removed namespaced storage (e.g., $_SESSION['app']['key']). Store keys directly: set('user.id', 42) → writes to $_SESSION['user.id']. Adjust legacy code accordingly.
• Validator Abstraction: If integrating with PSR-7 or custom auth, implement ValidatorInterface instead of relying on joomla/input. Add validators via $session->addValidator($validator).
• Handler vs Storage: HandlerInterface wraps PHP’s native session_set_save_handler() logic (e.g., DB, Redis), while StorageInterface handles $_SESSION interaction. A Redis-backed session needs both—a HandlerInterface implementation for persistence and NativeStorage (or custom) to bridge to Session.
• Token Regeneration Pitfall: getToken($forceNew = true) forces regeneration every time—use only once per login/logout. For forms, generate once per request: getToken(false).
• CLI Caution: Native storage still touches $_SESSION, but sessions may be empty in CLI unless session.auto_start=1 or manually started. Prefer RuntimeStorage for CLI commands unless you deliberately need persistence.
• Breaking v2 Changes: If migrating from v1, drop _underscored methods, remove namespacing, and ensure Input/Event\Dispatcher are injected at construction. The upgrade guide in docs/v1-to-v2-update.md is critical.