Sessions

Lightpack provides the session() function to work with sessions in a consistent, secure, and flexible way. The session system supports multiple storage drivers, dot notation for nested data, CSRF and agent validation, and more.

Quick Start

To use sessions, just call the global session() helper:

session()->set('user_id', 42);
$userId = session()->get('user_id');

Supported Methods

session()->set()
session()->get()
session()->has()
session()->delete()
session()->flash()
session()->regenerate()
session()->destroy()
session()->token()
session()->hasInvalidAgent()
session()->verifyAgent()
session()->setUserAgent()

Features & Usage

Setting Session Data

Set a value (including arrays/objects) for a key:

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

Supports dot notation for nested data:

session()->set('user.profile.name', 'Alice');

Getting Session Data

Get a value by key:

session()->get('key');

Get a nested value:

session()->get('user.profile.name');

Provide a default if the key isn’t found:

session()->get('key', 'default');

Get all session data:

session()->get();

Checking Existence

Check if a key (or nested key) exists:

session()->has('key');
session()->has('user.profile.name');

Deleting Session Data

Delete a key (or nested key):

session()->delete('key');
session()->delete('user.profile.name');

Flash Data

Flash data persists only for the next request (great for messages):

session()->flash('notice', 'Profile updated!'); // Set flash data
$notice = session()->flash('notice'); // Get and remove flash data

Regenerating Session ID

Regenerate the session ID (for security after login, etc):

session()->regenerate();

• Note: Also deletes the CSRF token.

Destroying the Session

Completely destroy the session and all its data:

session()->destroy();

Security Features

CSRF Token

Generate or retrieve a CSRF token:

$token = session()->token();

Inject the CSRF token in your form using the helper:

echo csrf_input(); // <input type="hidden" name="_token" value="...">

Or in a filter or controller, validate the submitted token:

$token = request()->input('_token');

if (! $token || $token !== session()->token()) {
    // Block the request - invalid CSRF token!
}

Lightpack provides a built-in csrf filter that automatically validates CSRF tokens on POST, PUT, PATCH, and DELETE requests. Just attach ->filter('csrf') to your routes instead of writing manual checks. Refer to the filters documentation for more details.

User Agent Validation

Store and verify the user agent string to help prevent session hijacking:

// Manually set agent
session()->setUserAgent('AppleWebKit/KHTML'); 

if(session()->hasInvalidAgent()) {
    // Block the request!
}

Advanced Features

Dot Notation for Nested Data

You can set, get, check, or delete deeply nested session data using dot notation:

session()->set('cart.items.0.product_id', 123);
$productId = session()->get('cart.items.0.product_id');
session()->delete('cart.items.0.product_id');
session()->has('cart.items.0.product_id');

Driver System

Lightpack sessions support multiple drivers, each with different storage backends:

• DefaultDriver: Uses PHP’s native $_SESSION (file-based).
• ArrayDriver: Stores data in-memory (great for tests).
• CacheDriver: Stores session in a cache backend.
• RedisDriver: Uses Redis for scalable, distributed sessions.
• EncryptedDriver: Encrypts session values at rest.

You can configure the driver in your app’s config.

Edge Cases & Notes

• Session keys can be any string. Use dot notation for nested arrays.
• Flash data is removed after it is read.
• Regenerating deletes the CSRF token for safety.
• If you use a custom driver, it must implement the DriverInterface.
• Session ID and cookie settings (name, lifetime, security flags) are configurable.
• EncryptedDriver requires a Crypto instance and will serialize/deserialize values automatically.
• ArrayDriver is not persistent and should only be used for testing.
• CacheDriver and RedisDriver handle session IDs and cookies internally, and support TTL (expiry).

Intended URL Helpers

Lightpack provides convenient helpers for managing "intended URLs" - URLs that users were trying to access before being redirected (typically to login). This is commonly used in authentication flows.

Setting Intended URL

Store the URL a user was trying to access:

session()->setIntendedUrl('/admin/settings');

Typically, the AuthFilter does this automatically for GET requests when redirecting unauthenticated users to login.

Getting Intended URL

Retrieve the stored intended URL:

$url = session()->getIntendedUrl();

With a default fallback:

$url = session()->getIntendedUrl('/dashboard');

Checking for Intended URL

Check if an intended URL exists:

if (session()->hasIntendedUrl()) {
    $url = session()->getIntendedUrl();
    // redirect to $url
}

Clearing Intended URL

Remove the stored intended URL:

session()->forgetIntendedUrl();

Configuration

Session settings (driver, name, lifetime, security, etc.) are controlled in your app's config file, typically config/session.php.