Session Library¶

Initializing a Session¶

Sessions will typically run globally with each page load, so the Session class should either be initialized in your controller constructors, or it can be auto-loaded by the system. For the most part the session class will run unattended in the background, so simply initializing the class will cause it to read, create, and update sessions when necessary.

To initialize the Session class manually in your controller constructor, use the $this->load->library() method:

$this->load->library('session');

Once loaded, the Sessions library object will be available using:

$this->session

How do Sessions work?¶

When a page is loaded, the session class will check to see if valid session cookie is sent by the user’s browser. If a sessions cookie does not exist (or if it doesn’t match one stored on the server or has expired) a new session will be created and saved.

If a valid session does exist, its information will be updated. With each update, the session ID may be regenerated if configured to do so.

It’s important for you to understand that once initialized, the Session class runs automatically. There is nothing you need to do to cause the above behavior to happen. You can, as you’ll see below, work with session data, but the process of reading, writing, and updating a session is automatic.

What is Session Data?¶

Session data is simply an array associated with a particular session ID (cookie).

If you’ve used sessions in PHP before, you should be familiar with PHP’s $_SESSION superglobal (if not, please read the content on that link).

CodeIgniter gives access to its session data through the same means, as it uses the session handlers’ mechanism provided by PHP. Using session data is as simple as manipulating (read, set and unset values) the $_SESSION array.

In addition, CodeIgniter also provides 2 special types of session data that are further explained below: flashdata and tempdata.

Retrieving Session Data¶

Any piece of information from the session array is available through the $_SESSION superglobal:

$_SESSION['item']

Or through the magic getter:

$this->session->item

And for backwards compatibility, through the userdata() method:

$this->session->userdata('item');

Where item is the array key corresponding to the item you wish to fetch. For example, to assign a previously stored ‘name’ item to the $name variable, you will do this:

$name = $_SESSION['name'];

// or:

$name = $this->session->name

// or:

$name = $this->session->userdata('name');

If you want to retrieve all of the existing userdata, you can simply omit the item key (magic getter only works for properties):

$_SESSION

// or:

$this->session->userdata();

Adding Session Data¶

Let’s say a particular user logs into your site. Once authenticated, you could add their username and e-mail address to the session, making that data globally available to you without having to run a database query when you need it.

You can simply assign data to the $_SESSION array, as with any other variable. Or as a property of $this->session.

Alternatively, the old method of assigning it as “userdata” is also available. That however passing an array containing your new data to the set_userdata() method:

$this->session->set_userdata($array);

Where $array is an associative array containing your new data. Here’s an example:

$newdata = array(
        'username'  => 'johndoe',
        'email'     => '[email protected]',
        'logged_in' => TRUE
);

$this->session->set_userdata($newdata);

If you want to add userdata one value at a time, set_userdata() also supports this syntax:

$this->session->set_userdata('some_name', 'some_value');

If you want to verify that a session value exists, simply check with isset():

// returns FALSE if the 'some_name' item doesn't exist or is NULL,
// TRUE otherwise:
isset($_SESSION['some_name'])

Or you can call has_userdata():

$this->session->has_userdata('some_name');

Removing Session Data¶

Just as with any other variable, unsetting a value in $_SESSION can be done through unset():

unset($_SESSION['some_name']);

// or multiple values:

unset(
        $_SESSION['some_name'],
        $_SESSION['another_name']
);

Also, just as set_userdata() can be used to add information to a session, unset_userdata() can be used to remove it, by passing the session key. For example, if you wanted to remove ‘some_name’ from your session data array:

$this->session->unset_userdata('some_name');

This method also accepts an array of item keys to unset:

$array_items = array('username', 'email');

$this->session->unset_userdata($array_items);

Flashdata¶

CodeIgniter supports “flashdata”, or session data that will only be available for the next request, and is then automatically cleared.

This can be very useful, especially for one-time informational, error or status messages (for example: “Record 2 deleted”).

It should be noted that flashdata variables are regular session vars, only marked in a specific way under the ‘__ci_vars’ key (please don’t touch that one, you’ve been warned).

To mark an existing item as “flashdata”:

$this->session->mark_as_flash('item');

If you want to mark multiple items as flashdata, simply pass the keys as an array:

$this->session->mark_as_flash(array('item', 'item2'));

To add flashdata:

$_SESSION['item'] = 'value';
$this->session->mark_as_flash('item');

Or alternatively, using the set_flashdata() method:

$this->session->set_flashdata('item', 'value');

You can also pass an array to set_flashdata(), in the same manner as set_userdata().

Reading flashdata variables is the same as reading regular session data through $_SESSION:

$_SESSION['item']

However, if you want to be sure that you’re reading “flashdata” (and not any other kind), you can also use the flashdata() method:

$this->session->flashdata('item');

Or to get an array with all flashdata, simply omit the key parameter:

$this->session->flashdata();

If you find that you need to preserve a flashdata variable through an additional request, you can do so using the keep_flashdata() method. You can either pass a single item or an array of flashdata items to keep.

$this->session->keep_flashdata('item');
$this->session->keep_flashdata(array('item1', 'item2', 'item3'));

Tempdata¶

CodeIgniter also supports “tempdata”, or session data with a specific expiration time. After the value expires, or the session expires or is deleted, the value is automatically removed.

Similarly to flashdata, tempdata variables are regular session vars that are marked in a specific way under the ‘__ci_vars’ key (again, don’t touch that one).

To mark an existing item as “tempdata”, simply pass its key and expiry time (in seconds!) to the mark_as_temp() method:

// 'item' will be erased after 300 seconds
$this->session->mark_as_temp('item', 300);

You can mark multiple items as tempdata in two ways, depending on whether you want them all to have the same expiry time or not:

// Both 'item' and 'item2' will expire after 300 seconds
$this->session->mark_as_temp(array('item', 'item2'), 300);

// 'item' will be erased after 300 seconds, while 'item2'
// will do so after only 240 seconds
$this->session->mark_as_temp(array(
        'item'  => 300,
        'item2' => 240
));

To add tempdata:

$_SESSION['item'] = 'value';
$this->session->mark_as_temp('item', 300); // Expire in 5 minutes

Or alternatively, using the set_tempdata() method:

$this->session->set_tempdata('item', 'value', 300);

You can also pass an array to set_tempdata():

$tempdata = array('newuser' => TRUE, 'message' => 'Thanks for joining!');

$this->session->set_tempdata($tempdata, NULL, $expire);

To read a tempdata variable, again you can just access it through the $_SESSION superglobal array:

$_SESSION['item']

Or if you want to be sure that you’re reading “tempdata” (and not any other kind), you can also use the tempdata() method:

$this->session->tempdata('item');

And of course, if you want to retrieve all existing tempdata:

$this->session->tempdata();

If you need to remove a tempdata value before it expires, you can directly unset it from the $_SESSION array:

unset($_SESSION['item']);

However, this won’t remove the marker that makes this specific item to be tempdata (it will be invalidated on the next HTTP request), so if you intend to reuse that same key in the same request, you’d want to use unset_tempdata():

$this->session->unset_tempdata('item');

Destroying a Session¶

To clear the current session (for example, during a logout), you may simply use either PHP’s session_destroy() function, or the sess_destroy() method. Both will work in exactly the same way:

session_destroy();

// or

$this->session->sess_destroy();

Accessing session metadata¶

In previous CodeIgniter versions, the session data array included 4 items by default: ‘session_id’, ‘ip_address’, ‘user_agent’, ‘last_activity’.

This was due to the specifics of how sessions worked, but is now no longer necessary with our new implementation. However, it may happen that your application relied on these values, so here are alternative methods of accessing them:

• session_id: session_id()
• ip_address: $_SERVER['REMOTE_ADDR']
• user_agent: $this->input->user_agent() (unused by sessions)
• last_activity: Depends on the storage, no straightforward way. Sorry!

Session Preferences¶

CodeIgniter will usually make everything work out of the box. However, Sessions are a very sensitive component of any application, so some careful configuration must be done. Please take your time to consider all of the options and their effects.

You’ll find the following Session related preferences in your application/config/config.php file:

In addition to the values above, the cookie and native drivers apply the following configuration values shared by the Input and Security classes:

Session Drivers¶

As already mentioned, the Session library comes with 4 drivers, or storage engines, that you can use:

• files
• database
• redis
• memcached

By default, the Files Driver will be used when a session is initialized, because it is the most safe choice and is expected to work everywhere (virtually every environment has a file system).

However, any other driver may be selected via the $config['sess_driver'] line in your application/config/config.php file, if you chose to do so. Have it in mind though, every driver has different caveats, so be sure to get yourself familiar with them (below) before you make that choice.

In addition, you may also create and use Custom Drivers, if the ones provided by default don’t satisfy your use case.

mkdir /<path to your application directory>/sessions/
chmod 0700 /<path to your application directory>/sessions/
chown www-data /<path to your application directory>/sessions/

$config['sess_driver'] = 'database';
$config['sess_save_path'] = 'ci_sessions';

CREATE TABLE IF NOT EXISTS `ci_sessions` (
        `id` varchar(128) NOT NULL,
        `ip_address` varchar(45) NOT NULL,
        `timestamp` int(10) unsigned DEFAULT 0 NOT NULL,
        `data` blob NOT NULL,
        KEY `ci_sessions_timestamp` (`timestamp`)
);

CREATE TABLE "ci_sessions" (
        "id" varchar(128) NOT NULL,
        "ip_address" varchar(45) NOT NULL,
        "timestamp" bigint DEFAULT 0 NOT NULL,
        "data" text DEFAULT '' NOT NULL
);

CREATE INDEX "ci_sessions_timestamp" ON "ci_sessions" ("timestamp");

// When sess_match_ip = TRUE
ALTER TABLE ci_sessions ADD PRIMARY KEY (id, ip_address);

// When sess_match_ip = FALSE
ALTER TABLE ci_sessions ADD PRIMARY KEY (id);

// To drop a previously created primary key (use when changing the setting)
ALTER TABLE ci_sessions DROP PRIMARY KEY;

$config['sess_driver'] = 'redis';
$config['sess_save_path'] = 'tcp://localhost:6379';

$config['sess_driver'] = 'memcached';
$config['sess_save_path'] = 'localhost:11211';

// localhost will be given higher priority (5) here,
// compared to 192.0.2.1 with a weight of 1.
$config['sess_save_path'] = 'localhost:11211:5,192.0.2.1:11211:1';

// application/libraries/Session/drivers/Session_dummy_driver.php:

class CI_Session_dummy_driver extends CI_Session_driver implements SessionHandlerInterface
{

        public function __construct(&$params)
        {
                // DO NOT forget this
                parent::__construct($params);

                // Configuration & other initializations
        }

        public function open($save_path, $name)
        {
                // Initialize storage mechanism (connection)
        }

        public function read($session_id)
        {
                // Read session data (if exists), acquire locks
        }

        public function write($session_id, $session_data)
        {
                // Create / update session data (it might not exist!)
        }

        public function close()
        {
                // Free locks, close connections / streams / etc.
        }

        public function destroy($session_id)
        {
                // Call close() method & destroy data for current session (order may differ)
        }

        public function gc($maxlifetime)
        {
                // Erase data for expired sessions
        }

}