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
$session = $kirby->session();
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
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
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.
You can do all sorts of cool stuff with the global session object:
$session->get('myplugin.mykey', 'my default value'); $session->set('myplugin.mykey', 'my new value');
$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.
$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.
$session->pull('myplugin.message', 'my default value');
$session->pull() removes the value from the session after getting it.
$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();
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.
Kirby periodically deletes expired sessions (so-called "garbage collection").
If your site has lots of users or if you create sessions for your site visitors, it might make sense to clean up expired sessions in the background to increase performance.
First you need to disable the automatic garbage collector in your Kirby config:
<?php return [ 'session' => [ 'gcInterval' => false ] ];
Now you can write a script with the following contents and periodically run it with a Cronjob (depending on the amount of sessions every few minutes to every few hours):
<?php require 'path/to/kirby/bootstrap.php'; $kirby = new Kirby(); $kirby->sessionHandler()->collectGarbage();
You can change the session settings with the
session option in your