1. INTRODUCTION

Sessions remember values between page visits. Use them for a selected theme, language or a message to display after submitting a form.

Kristal Framework starts the session for you. You can use Session directly in templates. In a namespaced PHP file, add this import near the top:

use Backend\Core\Session;

2. SAVING AND READING VALUES

Use add() to save a value. Saving under the same name replaces the previous value:

Session::add("display_name", "Alex");
Session::add("theme", "dark");
Session::add("selected_categories", ["news", "tutorials"]);

Read a saved value with get(). The second argument is the default when nothing has been saved:

$name = Session::get("display_name", "Visitor");
$theme = Session::get("theme", DEFAULT_THEME);

For example, display the name in a page template:

<p>Hello, <?= esc_html(Session::get("display_name", "Visitor")); ?>!</p>

To check whether a value exists:

if (Session::has("display_name"))
{
    echo "A name has been saved.";
}

has() returns true for a saved value, including false or 0. A null value is treated as missing.

3. REMOVING VALUES

Remove one value by name, or pass an array of names:

Session::remove("display_name");

Session::remove(["name_feedback", "form_values"]);

To read all session values or clear them:

$values = Session::getAll();
Session::removeAll();

For a message that appears once, read it, display it and remove it. The Forms guide shows how.

4. SESSION SETTINGS

You’ll find these settings in config/config.php:

• SESSION_NAME: The session cookie name. Choose one for your website.
• SESSION_LIFETIME: Cookie lifetime in seconds. Use 0 for a browser-session cookie.
• SESSION_AFK_TIMEOUT: How long a visitor can be inactive before the session restarts. Use 0 to disable the check.
• SESSION_REGENERATE_ID_TIME: How often the session ID changes, in seconds. Use 0 to disable automatic changes.
• SESSION_SAMESITE: The cookie’s SameSite setting, such as Lax.
• RESTART_SESSION_ON_VISITOR_MISMATCH: Restarts the session if the browser’s User-Agent changes.
• COOKIE_NAME: An additional cookie removed when end() or removeRememberCookie() is called.

The inactivity check happens on the next request. PHP’s own session storage settings also affect how long saved data remains available.

Kristal Framework sets the session cookie’s HTTPS flag from URL_BASE, so make sure the framework recognizes your site’s HTTPS connection.

5. REGENERATING AND ENDING A SESSION

To change the session ID while keeping its values:

Session::regenerateId();

To clear the session and return to the homepage:

Session::end();
redirect(route(""));

end() clears the values and removes the session cookie and the cookie named by COOKIE_NAME.

Use restart() to end the session and immediately start a fresh one. start() starts one only if none is active.

6. VISITOR INFORMATION

The Session class also provides a few helpers for the current request:

$ip = Session::getClientIPAddress();
$agent = Session::getUserAgent();
$device = Session::getDeviceLabel();
$identity = Session::getUniqueIdentity();

The IP address comes from REMOTE_ADDR. Device labels are simple descriptions such as Windows device or Android device. The identity value is based on the User-Agent; it isn’t a reliable way to identify an individual person or device.