trail / sessions

0.4.0 2026-10-18 07:43 UTC

Requires

• php: >=8.4
• trail/db: ^0.4.0
• trail/framework: ^0.4.0

MIT

• Alex Brindley

• cookies
• sessions
• trail

Published on Packagist.org on 2026-10-18 07:44 UTC

README

Session handling for trail framework

install

composer require trail/sessions
trail/trail db::migrate

Requires trail/db. Every request now has a Session in the box.

use it

Ask for it in handle(). Stuff is stored as json so keep that in mind.

use Trail\Sessions\Session\Session;

public function handle(Session $session): Response
{
    $session->put('theme', 'dark');
    $session->get('theme', 'light');
    $session->has('theme');
    $session->pull('once');              // get + forget
    $session->forget('theme');
    $session->flash('notice', 'saved');  // next request
    $session->flashed();                 // last request flashed

    ...
}

how it works

• nothing touches the database until something gets added
• cookie has a random token. table holds its sha256
• sessions that go empty delete their row + cookie
• busy sessions caress their row once a minute at most
• guest never comes back dies after an hour (bots, curl, whatever)
• registers with freeze addon so anyone with a session can skip cache

For auth addons (or whatever)

$session->claim($userId);   // set user + swap token
$session->renew();          // swap token + keep stuff
$session->destroy();        // wipe everything
$session->userId();

Locker lists and kills sessions per user. For "your devices" pages

$locker->forUser($userId);
$locker->evict($userId, $id);
$locker->evictAll($userId, except: $session->id);

config

In app.php

'sessions' => [

    // idle seconds before it dies. 2 weeks
    'lifetime' => 1209600,

    // https only cookie
    'secure' => true,

    // cookie name. __Host- before when secure
    'name' => 'trail_session',

    // full override
    'cookie' => null,
],

cli

Expired table rows hang around until you prune them. Cleanup with a command

trail/trail sessions::prune