Fuel Documentation

Session Class

The session class allows you to maintain state for your application in the stateless environment of the web. It allows you to store variables on the server using a variety of storage solutions, and recall these variables on the next page request.

The static methods documented on this page use the session driver configured in the configuration via the driver setting. When you have set the auto_initialize setting to true, the session will be loaded and initialized when the Fuel framework loads. If it is set to false, it will be loaded automatically as soon as you use one of the methods below.

Note that if you choose not to auto_initialize the session, and you don't use any of the session methods, the session will not be refreshed! This can cause unexpected behaviour of your application due to an expired session.

instance($instance = null)

The instance method returns the default session instance, or a specific instance, identified by name.

Static Yes
Parameters
Param Default Description
$instance optional Cookiename (as defined in config/session.php) that identifies the required session instance.
Returns mixed - session object, or false in case the requested instance does not exist.
Example
// get the default session instance (identified by the 'driver' configuration setting).
$session = Session::instance();

// get a specific session instance
$session = Session::instance('myappcookie');

set($variable, $value = null)

The set method allows you to set a session variable.

Static Yes
Parameters
Param Default Description
$name required Name of the session variable to set.
$value optional The session variables value.
This can be any data type, but pay attention when storing objects in the session, as session data is serialized, and there are restrictions to serializing an object.
Returns void
Example
// store the userid in the session
Session::set('userid', $userid);

// you can also store more complex values
Session::set('array', array('varA', 'varB', 'varC' => array('val1', 'val2'));

get($variable = null, $default = null)

The get method allows you to retrieve stored variables from the session.

Static Yes
Parameters
Param Default Description
$variable required Name of the session variable to get.
$default optional Default value to return in case the requested variable does not exist. If no default is given, the method will return null.
Returns mixed - Dependent on the type of the stored $variable. The method returns null if the requested variable does not exist.
Example
// get the stored userid from the session
$userid = Session::get('userid');
if ( $userid === false )
{
	echo "no user is logged in";
}

// you can retrieve the entire array stored
$arr = Session::get('array');

// or get a specific key from the array
$arr = Session::get('array.varC');

delete($variable)

The delete method allows you to delete a stored session variable.

Static Yes
Parameters
Param Default Description
$variable required Name of the session variable to delete.
Returns void
Example
// delete the stored userid from the session
Session::delete('userid');

// you can also delete a specific key from the array
Session::delete('array.varC');

set_flash($variable, $value = null)

The set_flash method allows you to set a session flash variable. Flash variables have a limited lifespan. Depending on the configuration, they will be deleted after the next page request, or after they are retrieved.

Static Yes
Parameters
Param Default Description
$name required Name of the session flash variable to set.
$value optional The session flash variables value.
This can be any data type, but pay attention when storing objects in the session, as session data is serialized, and there are restrictions to serializing an object.
Returns void
Example
// tell the next page request which step to process
Session::set_flash('step', 2);

// you can also store more complex values
Session::set_flash('array', array('varA', 'varB', 'varC' => array('val1', 'val2'));

get_flash($variable, $default = null)

The get_flash method allows you to get a session flash variable. Flash variables have a limited lifespan. Depending on the configuration, they will be deleted after the next page request, or after they are retrieved.

Static Yes
Parameters
Param Default Description
$variable required Name of the session variable to get.
$default optional Default value to return in case the requested variable does not exist. If no default is given, the method will return null.
Returns mixed - Dependent on the type of the stored $variable. The method returns null if the requested variable does not exist.
Example
// find out which step to process
$step = Session::get_flash('step');

keep_flash($variable)

The keep_flash method resets a flash variable stored in the session to an 'unrequested' state. This allows you to get a flash variable, and still pass it on to the next page request.

Static Yes
Parameters
Param Default Description
$variable required Name of the flash variable to keep.
Returns void
Example
// keep the step value for one more page request
Session::keep_flash('step');

delete_flash($variable)

The delete_flash method allows you to delete a stored flash variable.

Static Yes
Parameters
Param Default Description
$variable required Name of the flash variable to delete.
Returns void
Example
// delete the step from the session
Session::delete_flash('userid');

create()

The create method allows you to create a new session. If a session is already present, it will be destroyed when the new one is created.

Static Yes
Parameters None
Returns void
Example
// create a new session
Session::create();

destroy()

The destroy method allows you to destroy an existing session.

Static Yes
Parameters None
Returns void
Example
// destroy a session
Session::destroy();

read()

The read method allows you to manually read a session. The session is automatically read when the session class is initialized, so under normal circumstances there is no need to use this method.

Static Yes
Parameters None
Returns void
Example
// read the session
Session::read();

write()

The write method allows you to manually write the session. Under normal circumstances, the session is automatically written when the script ends.

Static Yes
Parameters None
Returns void
Example
// write the session
Session::write();