Sessions

About sessions

Sessions provide a way to preserve data across different HTTP requests of the same visitor. They are commonly used for login handling (the user logs in once and keeps their authentication during the session's duration), security checks (e.g. CSRF tokens) or user preferences (e.g. selected language, UI settings...).

Each session has a session ID that generally gets stored in a cookie in the visitor's browser. The actual data of the session is stored in a session file on the server that matches the session ID.

PHP natively provides session functions, however they are limited and often (depending on the hosting provider) not reliable enough for sessions that last more than a few hours.

Kirby therefore has its own global session object that you can access with $kirby->session():

$session = $kirby->session();

The session lifecycle

Unlike the native PHP sessions feature, Kirby only creates sessions when there's actual data being stored in them. You can therefore request the session object without triggering a session cookie being set, which means that you won't need a cookie warning unless you actually need to store anything in the session or the user logs in.

Once the first piece of information is stored in the session, the session gets created and a session cookie is transmitted to the visitor's browser.

Sessions last for two hours by default, after which they expire. This value can be configured with the session.durationNormal option. It is not possible to create sessions with infinite duration (= sessions that never expire), because that would make it impossible to clean up old session files from the server.

Sessions also have an activity timeout that will expire the session if there wasn't any activity in the last half an hour. It can be configured or disabled with the session.timeout option.

There are also so-called "long sessions". They don't have a timeout and expire after two weeks by default. The expiry time can be changed with the session.durationLong option.

Once half of the session duration is over, the session is automatically renewed on the next request. The new session has the same duration again, but a new session ID.

Using the session for your own data

You can do all sorts of cool stuff with the global session object:

Getting and setting

$session->get('myplugin.mykey', 'my default value');
$session->set('myplugin.mykey', 'my new value');

Incrementing

$session->set('myplugin.counter', 10);
$session->increment('myplugin.counter', 2, 50);
$session->get('myplugin.counter') // 12

The third param to $session->increment() is the maximum value; the value won't be incremented beyond that value.

Decrementing

$session->set('myplugin.counter', 10);
$session->decrement('myplugin.counter', 2, 0);
$session->get('myplugin.counter') // 8

The third param to $session->decrement() is the minimum value; the value won't be decremented beyond that value.

Pulling data out of the session

$session->pull('myplugin.message', 'my default value');

$session->pull() removes the value from the session after getting it.

Removing data

$session->remove('myplugin.mykey');

Clearing all session data

$session->clear();

Destroying the session completely

$session->destroy();

Interesting stats

$session->startTime();
$session->expiryTime();

// total duration between start and expiry time in seconds
$session->duration();

// seconds of inactivity after which the session will expire
$session->timeout();

Requesting a long session

If you want to use a "long" session (a session with a long duration and without timeout) in your controllers and templates, you can request it like this:

$session = $kirby->session(['long' => true]);

If a session already exists, it is automatically extended appropriately, so you don't have to deal with any edgecases.

Manually collecting garbage

<?php

return [
    'session' => [
        'gcInterval' => false
    ]
];

<?php

require 'path/to/kirby/bootstrap.php';

$kirby = new Kirby();
$kirby->sessionHandler()->collectGarbage();

Configuration

You can change the session settings with the session option in your /site/config/config.php.

All session options…