Sessions¶

Session Configuration¶

Session configuration is stored in Configure under the top level Session key, and a number of options are available:

• Session.cookie - Change the name of the session cookie.

• Session.timeout - The number of minutes before CakePHP’s session handler expires the session. This affects Session.autoRegenerate (below), and is handled by CakeSession.

• Session.cookieTimeout - The number of minutes before the session cookie expires. If this is undefined, it will use the same value as Session.timeout. This affects the session cookie, and is handled by PHP itself.

• Session.checkAgent - Should the user agent be checked, on each request. If the user agent does not match the session will be destroyed.

• Session.autoRegenerate - Enabling this setting, turns on automatic renewal of sessions, and session ids that change frequently. Enabling this value will use the session’s Config.countdown value to keep track of requests. Once the countdown reaches 0, the session id will be regenerated. This is a good option to use for applications that need frequently changing session ids for security reasons. You can control the number of requests needed to regenerate the session by modifying CakeSession::$requestCountdown.

• Session.defaults - Allows you to use one the built-in default session configurations as a base for your session configuration.

• Session.handler - Allows you to define a custom session handler. The core database and cache session handlers use this. This option replaces Session.save in previous versions. See below for additional information on Session handlers.

• Session.ini - Allows you to set additional session ini settings for your config. This combined with Session.handler replace the custom session handling features of previous versions

• Session.cacheLimiter - Allows you define the cache control headers used for the session cookie. The default is must-revalidate. This option was added in 2.8.0.

CakePHP’s defaults to setting session.cookie_secure to true, when your application is on an SSL protocol. If your application serves from both SSL and non-SSL protocols, then you might have problems with sessions being lost. If you need access to the session on both SSL and non-SSL domains you will want to disable this:

Configure::write('Session', array(
    'defaults' => 'php',
    'ini' => array(
        'session.cookie_secure' => false
    )
));

Session cookie paths default to / in 2.0, to change this you can use the session.cookie_path ini flag to the directory path of your application:

Configure::write('Session', array(
    'defaults' => 'php',
    'ini' => array(
        'session.cookie_path' => '/app/dir'
    )
));

If you are using php’s default session settings, take note that session.gc_maxlifetime can override your setting for timeout. The default is 24 minutes. Change this in your ini settings to get it to match longer sessions:

Configure::write('Session', array(
    'defaults' => 'php',
    'timeout' => 2160, // 36 hours
    'ini' => array(
        'session.gc_maxlifetime' => 129600 // 36 hours
    )
));

Built-in Session handlers & configuration¶

CakePHP comes with several built-in session configurations. You can either use these as the basis for your session configuration, or you can create a fully custom solution. To use defaults, simply set the ‘defaults’ key to the name of the default you want to use. You can then override any sub setting by declaring it in your Session config:

Configure::write('Session', array(
    'defaults' => 'php'
));

The above will use the built-in ‘php’ session configuration. You could augment part or all of it by doing the following:

Configure::write('Session', array(
    'defaults' => 'php',
    'cookie' => 'my_app',
    'timeout' => 4320 //3 days
));

The above overrides the timeout and cookie name for the ‘php’ session configuration. The built-in configurations are:

• php - Saves sessions with the standard settings in your php.ini file.

• cake - Saves sessions as files inside app/tmp/sessions. This is a good option when on hosts that don’t allow you to write outside your own home dir.

• database - Use the built-in database sessions. See below for more information.

• cache - Use the built-in cache sessions. See below for more information.

Configure::write('Session', array(
    'userAgent' => false,
    'cookie' => 'my_cookie',
    'timeout' => 600,
    'handler' => array(
        array('Foo', 'open'),
        array('Foo', 'close'),
        array('Foo', 'read'),
        array('Foo', 'write'),
        array('Foo', 'destroy'),
        array('Foo', 'gc'),
    ),
    'ini' => array(
        'cookie_secure' => 1,
        'use_trans_sid' => 0
    )
));

Configure::write('Session', array(
    'defaults' => 'database',
    'handler' => array(
        'model' => 'CustomSession'
    )
));

Configure::write('Session', array(
    'defaults' => 'database'
));

CREATE TABLE `cake_sessions` (
  `id` varchar(255) NOT NULL DEFAULT '',
  `data` text,
  `expires` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`)
);

$ Console/cake schema create sessions

Configure::write('Session', array(
    'defaults' => 'cache',
    'handler' => array(
        'config' => 'session'
    )
));

Setting ini directives¶

The built-in defaults attempt to provide a common base for session configuration. You may need to tweak specific ini flags as well. CakePHP exposes the ability to customize the ini settings for both default configurations, as well as custom ones. The ini key in the session settings, allows you to specify individual configuration values. For example you can use it to control settings like session.gc_divisor:

Configure::write('Session', array(
    'defaults' => 'php',
    'ini' => array(
        'session.gc_divisor' => 1000,
        'session.cookie_httponly' => true
    )
));

Creating a custom session handler¶

Creating a custom session handler is straightforward in CakePHP. In this example we’ll create a session handler that stores sessions both in the Cache (apc) and the database. This gives us the best of fast IO of apc, without having to worry about sessions evaporating when the cache fills up.

First we’ll need to create our custom class and put it in app/Model/Datasource/Session/ComboSession.php. The class should look something like:

App::uses('DatabaseSession', 'Model/Datasource/Session');

class ComboSession extends DatabaseSession implements CakeSessionHandlerInterface {
    public $cacheKey;

    public function __construct() {
        $this->cacheKey = Configure::read('Session.handler.cache');
        parent::__construct();
    }

    // read data from the session.
    public function read($id) {
        $result = Cache::read($id, $this->cacheKey);
        if ($result) {
            return $result;
        }
        return parent::read($id);
    }

    // write data into the session.
    public function write($id, $data) {
        Cache::write($id, $data, $this->cacheKey);
        return parent::write($id, $data);
    }

    // destroy a session.
    public function destroy($id) {
        Cache::delete($id, $this->cacheKey);
        return parent::destroy($id);
    }

    // removes expired sessions.
    public function gc($expires = null) {
        Cache::gc($this->cacheKey);
        return parent::gc($expires);
    }
}

Our class extends the built-in DatabaseSession so we don’t have to duplicate all of its logic and behavior. We wrap each operation with a Cache operation. This lets us fetch sessions from the fast cache, and not have to worry about what happens when we fill the cache. Using this session handler is also easy. In your core.php make the session block look like the following:

Configure::write('Session', array(
    'defaults' => 'database',
    'handler' => array(
        'engine' => 'ComboSession',
        'model' => 'Session',
        'cache' => 'apc'
    )
));

// Make sure to add a apc cache config
Cache::config('apc', array('engine' => 'Apc'));

Now our application will start using our custom session handler for reading & writing session data.

class CakeSession¶

Reading & writing session data¶

Depending on the context you are in, your application has different classes that provide access to the session. In controllers you can use SessionComponent. In the view, you can use SessionHelper. In any part of your application you can use CakeSession to access the session as well. Like the other interfaces to the session, CakeSession provides a simple CRUD interface.

static CakeSession::read($key)¶

You can read values from the session using Set::classicExtract() compatible syntax:

CakeSession::read('Config.language');

static CakeSession::write($key, $value)¶

$key should be the dot separated path you wish to write $value to:

CakeSession::write('Config.language', 'eng');

static CakeSession::delete($key)¶

When you need to delete data from the session, you can use delete:

CakeSession::delete('Config.language');

You should also see the documentation on Sessions and SessionHelper for how to access Session data in the controller and view.