Documentation

Configuration

The session class is configured through the fuel/core/config/session.php configuration file. It is already populated with a default configuration. You can override this configuration by copying this config file to your application config directory, and modify that file as needed.

The following global configuration values can be defined:

true

'cookie'

false

true

''

'/'

false

7200

false

300

'flash'

true

''

'Session-Id'

true

false

array(
	'cookie_name'    => 'fuelcid',
	'write_on_set'   => true
 )

array(
	'cookie_name'    => 'fuelfid',
	'path'           => '/tmp',
	'gc_probability' => 5
 )

array(
	'cookie_name'    => 'fueldid',
	'database'       => 'development',
	'table'          => 'sessions',
	'gc_probability' => 5
 )

array(
	'cookie_name'    => 'fuelmid',
	'servers'        => array( 'default' =>
							array(
								'host' => '127.0.0.1',
								'port' => 11211,
								'weight' => 100
							)
						)
 )

array(
	'cookie_name'    => 'fuelrid',
	'database'       => 'default'
 )

For each of the session storage drivers, a separate configuration section exists. This section contains the driver specific parameters, and you can use it to override global parameters for that specific storage driver.

The Session class checks the following locations for a session id, in this order. It doesn't validate at this point, the first value found is used, and if that turns out not to be valid, a new session is created:

• Posted data, it will check Input::post for the variable defined in "post_cookie_name".
• Cookies, it will check for a valid cookie with the name defined in "cookie_name".
• Get data, it will check Input::get for the variable with the name defined in "cookie_name".
• http headers, it will check for the header with the name defined in "http_header_name".

The session class configuration is independent from the cookie class configuration. It is important that you configure the cookie_domain and cookie_path items correctly. Notably, the domain 'localhost' is not accepted as valid by most modern browsers!

'fuelcid'

'fuelfid'

'/tmp'

5

'fueldid'

null

'sessions'

CREATE TABLE IF NOT EXISTS `sessions` (
  `session_id` varchar(40) NOT NULL,
  `previous_id` varchar(40) NOT NULL,
  `user_agent` text NOT NULL,
  `ip_hash` char(32) NOT NULL DEFAULT '',
  `created` int(10) unsigned NOT NULL DEFAULT '0',
  `updated` int(10) unsigned NOT NULL DEFAULT '0',
  `payload` longtext NOT NULL,
  PRIMARY KEY (`session_id`),
  UNIQUE KEY `PREVIOUS` (`previous_id`)
) ENGINE=INNODB DEFAULT CHARSET=utf8;

5

'fuelmid'

array (
	'default' =>
		array(
			'host' => '127.0.0.1',
			'port' => 11211,
			'weight' => 100
		)
)

'fuelrid'

'default'

Using Oil to Create/Control Your Sessions Table

An oil task has been provided to allow you to create, remove and clear your sessions table using the oil command line utility.

# display menu
$ php oil r session

# create the sessions table
$ php oil r session:create

# remove the sessions table
$ php oil r session:remove

# clear (truncate) the sessions table
$ php oil r session:clear

PHP native session emulation

When activated via the configuration, the Session class will enable some basic emulation of PHP's native session mechanism that can be accessed via the $_SESSION global variable. This only works on the default session instance, the one accessable via the static interface.

When enabled, the Session class will setup a custom session handler, that will capture the calls to the PHP functions session_start(), session_close() and session_write_close(). If will force a close at shutdown when an open native session is detected.

• When session_start() is called, all session data stored in the Fuel session store you have configured will be copied into the $_SESSION array, so it can be accessed by non-Fuel code requiring sessions.
• When the session is closed, a diff is made and changes in $_SESSION are copied back into the Fuel session store.

This mechanism means that if you have a session variable that is modified both inside- and outside Fuel, it is undetermined which of the changes will be saved. This depends on the position of the last session_close() call in the code. If the session is not closed, Fuel's shutdown event will close it, and it will overwrite any data set via standard Session calls!