Skip to content

session

Jump to bottom
Benyamin Khalife edited this page May 11, 2026 · 1 revision

Session

The Session class provides a clean, static interface for managing PHP sessions in Webrium applications. It handles the full session lifecycle, flash messages, array helpers, counters, and security features like session regeneration.

Table of Contents

Getting Started

The session starts automatically the first time you call any Session method. You can also start it explicitly:

use Webrium\Session;

Session::start();

To customize where session files are stored, call setSavePath() before any other session method:

Session::setSavePath('/var/app/sessions');
Session::start();

Storing & Retrieving Data

set()

Store one or multiple values in the session:

// Single value
Session::set('user_id', 42);

// Multiple values at once
Session::set([
    'user_id' => 42,
    'role'    => 'admin',
    'locale'  => 'en',
]);

get()

Retrieve a value, with an optional default if the key does not exist:

$userId = Session::get('user_id');

// With a default fallback
$locale = Session::get('locale', 'en');

pull() / once()

Retrieve a value and immediately remove it from the session. Both methods are identical:

$token = Session::pull('csrf_token');
// or
$token = Session::once('csrf_token');

// $token now holds the value; 'csrf_token' is gone from the session

all()

Get the entire session as an associative array:

$data = Session::all();

has() / exists()

has() returns true if the key is set (even if its value is null).
exists() returns true only if the key is set and its value is not null.

if (Session::has('user_id')) {
    // key is set
}

if (Session::exists('user_id')) {
    // key is set and not null
}

Both methods accept an array of keys and return true only when all keys pass the check:

if (Session::has(['user_id', 'role'])) {
    // both keys are present
}

Removing Data

// Remove a single key
Session::forget('user_id');

// Remove multiple keys
Session::forget(['user_id', 'role', 'locale']);

// remove() is an alias for forget()
Session::remove('user_id');

Both forget() and remove() return true if at least one key was successfully removed.

Array Helper

Push a value onto a session key that holds an array. If the key does not exist or is not an array, it is initialized automatically:

Session::push('notifications', 'Your profile was updated.');
Session::push('notifications', 'You have a new message.');

$notifications = Session::get('notifications');
// ['Your profile was updated.', 'You have a new message.']

Flash Data

Flash data is stored for the current request and automatically deleted after the next request. It is ideal for one-time messages such as success alerts or validation errors.

flash()

// Single flash value
Session::flash('status', 'Profile updated successfully.');

// Multiple flash values
Session::flash([
    'status' => 'Profile updated.',
    'type'   => 'success',
]);

getFlash()

Retrieve a flash value just like a regular session value:

$message = Session::getFlash('status');

// With a default fallback
$message = Session::getFlash('status', 'No message.');

In your view or template:

<?php if (Session::has('status')): ?>
    <div class="alert"><?= Session::getFlash('status') ?></div>
<?php endif; ?>

reflash()

Keep flash data alive for one additional request:

// Keep all flash data
Session::reflash();

// Keep specific keys only
Session::reflash('status');
Session::reflash(['status', 'type']);

Counters

Increment or decrement an integer stored in the session:

// Increment by 1 (default)
Session::increment('login_attempts');

// Increment by a custom amount
Session::increment('score', 10);

// Decrement by 1 (default)
Session::decrement('credits');

// Decrement by a custom amount
Session::decrement('credits', 5);

Both methods return the new value after the operation:

$attempts = Session::increment('login_attempts');

if ($attempts >= 5) {
    // Too many attempts — lock the account
}

Session Lifecycle

start()

Start or resume the session. Safe to call multiple times — subsequent calls do nothing if the session is already active. Returns true if the session was started by this call, false if it was already running.

Session::start();

Check if the session is currently active:

if (Session::isStarted()) {
    // session is active
}

destroy() / clear()

Completely destroy the session: clears all data, deletes the session cookie, and ends the session. Both methods are identical.

Session::destroy();
// or
Session::clear();

Typical use after logout:

Session::regenerate();   // prevent session fixation
Session::destroy();
header('Location: /login');
exit;

flush()

Clear all session data but keep the session active:

Session::flush();
// Session is still running, but $_SESSION is now empty

regenerate()

Generate a new session ID. Call this after login or any privilege elevation to prevent session fixation attacks:

Session::regenerate();               // deletes old session file (default)
Session::regenerate(false);          // keeps old session file

Session Identity

Get or set the session ID:

$id = Session::id();

// Set a custom ID (must be called before start)
Session::id('custom-session-id');

Get or set the session name (the cookie name, default is PHPSESSID):

$name = Session::name();

// Set a custom name (must be called before start)
Session::name('my_app_session');

Cookie Configuration

Control the session cookie lifetime:

// Set lifetime to 2 hours
Session::setLifetime(7200);

// Expires when the browser closes (0 = session cookie)
Session::setLifetime(0);

$seconds = Session::getLifetime();

Set all cookie parameters at once (call before start()):

Session::setCookieParams(
    lifetime: 3600,
    path: '/',
    domain: '.example.com',
    secure: true,       // HTTPS only
    httponly: true      // not accessible via JavaScript
);

Get the current cookie parameters:

$params = Session::getCookieParams();
// [
//   'lifetime' => 3600,
//   'path'     => '/',
//   'domain'   => '.example.com',
//   'secure'   => true,
//   'httponly' => true,
// ]

API Reference

Lifecycle Methods

Method Description
Session::start() Start or resume the session
Session::isStarted() Check if the session is active
Session::regenerate($deleteOld) Regenerate the session ID
Session::destroy() Destroy the session and delete the cookie
Session::clear() Alias for destroy()
Session::flush() Clear all session data without destroying the session
Session::setSavePath($path) Set a custom session file storage path

Data Methods

Method Description
Session::set($key, $value) Store one or multiple values
Session::get($key, $default) Retrieve a value
Session::pull($key, $default) Retrieve and remove a value
Session::once($key, $default) Alias for pull()
Session::has($key) Check if a key is set
Session::exists($key) Check if a key is set and not null
Session::all() Get all session data
Session::forget($keys) Remove one or multiple keys
Session::remove($keys) Alias for forget()
Session::push($key, $value) Push a value onto a session array

Flash Methods

Method Description
Session::flash($key, $value) Store flash data for the next request
Session::getFlash($key, $default) Retrieve flash data
Session::reflash($keys) Keep flash data for one more request

Counter Methods

Method Description
Session::increment($key, $amount) Increment a session integer value
Session::decrement($key, $amount) Decrement a session integer value

Identity & Cookie Methods

Method Description
Session::id($id) Get or set the session ID
Session::name($name) Get or set the session name
Session::setLifetime($seconds) Set the session cookie lifetime
Session::getLifetime() Get the session cookie lifetime
Session::setCookieParams(...) Set all cookie parameters
Session::getCookieParams() Get all cookie parameters

Clone this wiki locally