Overview

Vespula Session is a lightweight PHP session management library that provides a simple interface for working with PHP sessions.

It builds on PHP’s native session functionality and adds a few useful features:

  • A namespaced session container to keep library data separate from other application session data.

  • Named segments for organizing session values.

  • Configurable idle timeouts.

  • Flash messages for storing one-time messages.

  • CSRF token generation and validation.

  • Support for custom PHP session save handlers.

The library deliberately avoids trying to replace PHP’s session functionality. It provides a small layer on top of it, with a focus on simplicity and predictable behaviour.

Session containers and segments

Vespula Session stores its data inside a single entry in the PHP $_SESSION array:

$_SESSION['VespulaSession'];

Within this container, data is organized into segments. The default segment is used for ordinary session values, while additional named segments can be created to keep different types of data separate.

For example, an application might use the default segment for general application data and a separate segment for authentication information.

This organization helps prevent different parts of an application from accidentally overwriting each other’s session values.

Installation

Install the package using Composer:

composer require vespula/session

The library uses PHP’s native session functionality. Ensure that PHP sessions are enabled and that the configured session storage is writable by PHP.

Quick example

A basic example of creating and using a session:

<?php
use Vespula\\Session\\Session;

// Create the session manager
$session = new Session();

// Start the PHP session
$session->start();

// Store a value
$session->set('username', 'juser');

// Retrieve a value
$username = $session->get('username');

// Retrieve a value with a default
$theme = $session->get('theme', 'light');

The session must be started before accessing session data. Configuration options can be supplied when calling start(), or set using the appropriate configuration methods before starting the session.

See Usage Guide for more details.