Non static session - markstory/cakephp GitHub Wiki

This is a work in progress

Problems with static sessions

CakePHP's session adapters have always been static. This has been a mixed blessing as it emulates the behavior of PHP's native sessions, but complicates testing, and promotes misuse of the session data. The most useful parts of the session features are the component & helper. The add nice object based interfaces to the session and make testing much simpler.

Making the session a request object feature

Because session data is inherently part of the request data, we should make that connection explict by exposting session data through the request object. This would enable usage like:

<?php
$id = $this->request->session()->get('User.id');

The session could be injected into a request when it is constructed as part of the parameters used for Request::__construct():

<?php
$storage = new DatabaseSession(Configure::read('Session'));
$session = new Session($storage);
$request = new Request(['session' => $session]);

The Request::createFromGlobals() method would use the data in Configure to create the correct session storage object and apply the remaining session configuration. If a request is created without the 'session' parameter, a Session object with the basic NativeSessionStorage adapter, with the default configuration values will be used.

Configuration

Configuration is one of the session features that works well. The same keys could be used in the future as are used now. The main difference would be that default configuration data would be contained in the storage engines.

Testing

In addition to the active session backends we should provide an ArraySession adapter that does not use actually call any ext/session methods, start or write to any session storage. This will help solve issues with saving sessions in CLI mode, and keep code performant in tests as database/file writes are avoided.

Usage

The session object would offer a similar interface to what it has today. By using Hash, it could provide dot path access to session data. The methods offered by the session object could be:

  • read($value, $default = null) - Read session data with a default value if the key/path returns null.
  • write($key, $value) - Write data to the session. $key can be a path.
  • delete($key) - Remove a path from the session.
  • check($key) - See if a path exists.
  • started() - See if the session has been started.
  • start() - Start the session. This will happen implicitly on the first IO operation.
  • close() - Close the session and write to the storage.
  • id() - Get/set the session id.
  • name() - Get/set the session cookie name.
  • valid() - See if the session is valid. Sessions are invalidated when they time out.
  • clear() - Removes all data in the session.
  • renew() - Regenerate the session id & migrate the session data. This will also renew the session cookie's expiry time.
  • flash($type, $message, $options) Write a flash message of a given type and $options.
  • deleteFlash($type) Remove flash message of a given type.

Session flash messages

In the past CakePHP has only supported a single flash message. For 3.0 we should add multiple 'types' of flash messages. Most applications have different kinds of flash messages for errors, warning, or success messages:

<?php
// On the request
$request->session()->flash('error', 'You did it wrong', $options);

// On the SessionComponent.
$this->Session->flash('error', 'You did it wrong', $options);

The $options array allows you to pass additional context or data to the flash message. Flash messages will persist in the session until they are removed. Most frequently flash messages will be displayed with the SessionHelper.

Showing flash messages

To show a flash message, you would use the SessionHelper just like before:

<?php
// Use the default element
echo $session->flash('warning');

// Use a custom element
echo $session->flash('warning', ['element' => 'flash/warning']);

Once displayed the flash message will be removed from the session.

Other changes to CakePHP

  • Request countdown & auto-regeneration features will be removed. These provide very little real world security and is often disabled because it complicates interactive client side applications. Or any applications that rely on concurrent requests.
  • User agent hashing will be removed. This feature is also generally not very useful and has caused issues in the past with tools like chrome frame.
  • The testAction method could be updated to accept a list of known session data to make testing simpler and more encapsulated.

SessionComponent

The component would basically provides a facade to the session object. Being a small shim around the request object interface, it would be quite small and generally just allow existing users to migrate more easily, and use an interface that requires less typing to use.

SessionHelper

The session helpers primary feature is displaying flash messages. This will continue to be true. The flash message features will be enhanced to allow displaying multiple kinds of flash messages.

<?php
echo $session->flash('warning', $options);