Session Library¶

The Session class permits you maintain a user’s “state” and track their activity while they browse your site.

Using the Session Class
Class Reference

Sessions will typically run globally with each page load, so the Session class should either be initialized in your controller constructors. 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->library() method:

                      $this->library('session');
                    

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

                      $this->session
                    

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).

Codingox 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.

Retrieving Session Data ¶

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

                      $_SESSION['item']
                    

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

                      $this->session->value('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->value('name');

Note

The value() method returns NULL if the item you are trying to access does not exist.

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->value();

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_value() method:

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

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

                      $newdata = array(
        'username'  => 'johndoe',
        'email'     => 'johndoe@some-site.com',
        'logged_in' => TRUE
);

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

                    

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

                      $this->session->set_value('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'])

                    

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_value() can be used to add information to a session, unset_session() 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_session('some_name');
                    

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

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

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

Flashdata ¶

Codingox 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”).

To add flashdata using the set_flash() method:

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

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

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 flash() method:

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

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

                      $this->session->flash();
                    

Note

The flash() method returns NULL if the item cannot be found.

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 destroy_session() method. Both will work in exactly the same way:

                      session_destroy();

// or

$this->session->destroy_session();

Note

This must be the last session-related operation that you do during the same request. All session data will be destroyed permanently and functions will be unusable during the same request after you destroy the session.

Session Preferences ¶

Codingox 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 config/config.php file:

Preference	Default	Options	Description
SESSION_NAME	session	None	The name used for the session cookie.
SESSION_TIME	7200 (2 hours)	Time in seconds (integer)	The number of seconds you would like the session to last. If you would like a non-expiring session (until browser is closed) set the value to zero: 0
SESSION_PATH	NULL	None	Specifies the storage location, depends on the driver being used.

Preference	Default	Description
COOKIE_DOMAIN	‘’	The domain for which the session is applicable
COOKIE_PATH	/	The path to which the session is applicable
COOKIE_SECURE	FALSE	Whether to create the session cookie only on encrypted (HTTPS) connections

Note

The ‘COOKIE_HTTPONLY’ setting doesn’t have an effect on sessions. Instead the HttpOnly parameter is always enabled.

Class Reference ¶

class session¶

value($key)¶

Parameters:	$key (mixed) – Session item key
Returns:	Value of the specified item key, or an array of all userdata
Return type:	mixed

Gets the value for a specific $_SESSION item, or an array of all “userdata” items if not key was specified.

Note

This is a legacy method kept only for backwards compatibility with older applications. You should directly access $_SESSION instead.

set_value($data, $value = NULL)¶

Parameters:	$data (mixed) – An array of key/value pairs to set as session data, or the key for a single item $value (mixed) – The value to set for a specific session item, if $data is a key
Return type:	void

Assigns data to the $_SESSION superglobal.

Note

This is a legacy method kept only for backwards compatibility with older applications.

unset_session($key)¶

Parameters:	$key (mixed) – Key for the session data item to unset, or an array of multiple keys
Return type:	void

Unsets the specified key(s) from the $_SESSION superglobal.

Note

This is a legacy method kept only for backwards compatibility with older applications. It is just an alias for unset($_SESSION[$key]) - please use that instead.

flash($key = NULL)¶

Parameters:	$key (mixed) – Flashdata item key or NULL
Returns:	Value of the specified item key, or an array of all flashdata
Return type:	mixed

Gets the value for a specific $_SESSION item that has been marked as “flashdata”, or an array of all “flashdata” items if no key was specified.

Note

This is a legacy method kept only for backwards compatibility with older applications. You should directly access $_SESSION instead.

set_flash($data, $value = NULL)¶

Parameters:	$data (mixed) – An array of key/value pairs to set as flashdata, or the key for a single item $value (mixed) – The value to set for a specific session item, if $data is a key
Return type:	void

Assigns data to the $_SESSION superglobal and marks it as “flashdata”.

Note

This is a legacy method kept only for backwards compatibility with older applications.

destroy_session()¶

Return type:	void

Destroys the current session.

Note

This must be the last session-related function that you call. All session data will be lost after you do that.

Note

This method is just an alias for PHP’s native session_destroy() function.

Session Library¶

Using the Session Class ¶

Initializing a Session ¶

What is Session Data?¶

Retrieving Session Data ¶

Adding Session Data ¶

Removing Session Data ¶

Flashdata ¶

Destroying a Session ¶

Session Preferences ¶

Class Reference ¶