Sessions

Sessions
     Storing, Retrieving, and Deleting Data
         Storing Data
         Retrieving Data
         Deleting Data
     Session Configuration
     Session Adapters
         Session Adapter Settings
             Native Adapter
             Cookie Adapter
             Database Adapter
                 Table Schema
                 Table Columns

Kohana provides classes that make it easy to work with both cookies and sessions. At a high level both sessions and cookies provide the same functionality. They allow the developer to store temporary or persistent information about a specific client for later retrieval, usually to make something persistent between requests.

Sessions should be used for storing temporary or private data. Very sensitive data should be stored using the Session class with the "database" or "native" adapters. When using the "cookie" adapter, the session should always be encrypted.

For more information on best practices with session variables see the seven deadly sins of sessions.

Storing, Retrieving, and Deleting Data

Cookie and Session provide a very similar API for storing data. The main difference between them is that sessions are accessed using an object, and cookies are accessed using a static class.

Accessing the session instance is done using the Session::instance method:

// Get the session instance
$session = Session::instance();

When using sessions, you can also get all of the current session data using the Session::as_array method:

// Get all of the session data as an array
$data = $session->as_array();

You can also use this to overload the $_SESSION global to get and set data in a way more similar to standard PHP:

// Overload $_SESSION with the session data
$_SESSION =& $session->as_array();

// Set session data
$_SESSION[$key] = $value;

Storing Data

Storing session or cookie data is done using the set method:

// Set session data
$session->set($key, $value);
// Or
Session::instance()->set($key, $value);

// Store a user id
$session->set('user_id', 10);

Retrieving Data

Getting session or cookie data is done using the get method:

// Get session data
$data = $session->get($key, $default_value);

// Get the user id
$user = $session->get('user_id');

Deleting Data

Deleting session or cookie data is done using the delete method:

// Delete session data
$session->delete($key);


// Delete the user id
$session->delete('user_id');

Session Configuration

Always check these settings before making your application live, as many of them will have a direct affect on the security of your application.

Session Adapters

When creating or accessing an instance of the Session class you can decide which session adapter or driver you wish to use. The session adapters that are available to you are:

Native
Stores session data in the default location for your web server. The storage location is defined by session.save_path in php.ini or defined by ini_set.
Database
Stores session data in a database table using the Session_Database class. Requires the Database module to be enabled.
Cookie
Stores session data in a cookie using the Cookie class. Sessions will have a 4KB limit when using this adapter, and should be encrypted.

The default adapter can be set by changing the value of Session::$default. The default adapter is "native".

To access a Session using the default adapter, simply call Session::instance(). To access a Session using something other than the default, pass the adapter name to instance(), for example: Session::instance('cookie')

Session Adapter Settings

You can apply configuration settings to each of the session adapters by creating a session config file at APPPATH/config/session.php. The following sample configuration file defines all the settings for each adapter:

As with cookies, a "lifetime" setting of "0" means that the session will expire when the browser is closed.

return [
    'native' => [
        'name' => 'session_name',
        'lifetime' => 43200,
    ],
    'cookie' => [
        'name' => 'cookie_name',
        'encrypted' => true,
        'lifetime' => 43200,
    ],
    'database' => [
        'name' => 'cookie_name',
        'encrypted' => true,
        'lifetime' => 43200,
        'group' => 'default',
        'table' => 'table_name',
        'columns' => [
            'session_id' => 'session_id',
            'last_active' => 'last_active',
            'contents' => 'contents'
        ],
        'gc' => 500,
    ],
];

Native Adapter

Type Setting Description Default
string name name of the session "session"
integer lifetime number of seconds the session should live for 0
Type Setting Description Default
string name name of the cookie used to store the session data "session"
boolean encrypted encrypt the session data using Encrypt? false
integer lifetime number of seconds the session should live for 0

Database Adapter

Type Setting Description Default
string group Database::instance group name "default"
string table table name to store sessions in "sessions"
array columns associative array of column aliases array
integer gc 1:x chance that garbage collection will be run 500
string name name of the cookie used to store the session data "session"
boolean encrypted encrypt the session data using Encrypt? false
integer lifetime number of seconds the session should live for 0
Table Schema

You will need to create the session storage table in the database. This is the default schema:

CREATE TABLE  `sessions` (
    `session_id` VARCHAR(24) NOT NULL,
    `last_active` INT UNSIGNED NOT NULL,
    `contents` TEXT NOT NULL,
    PRIMARY KEY (`session_id`),
    INDEX (`last_active`)
) ENGINE = MYISAM;
Table Columns

You can change the column names to match an existing database schema when connecting to a legacy session table. The default value is the same as the key value.

session_id
the name of the "id" column
last_active
UNIX timestamp of the last time the session was updated
contents
session data stored as a serialized string, and optionally encrypted