Session API¶

The Session class implements SessionInterface.

The Session has a simple API as follows divided into a couple of groups.

Session workflow

• start(): Starts the session - do not use session_start();
• migrate(): Regenerates the session ID - do not use session_regenerate_id(). This method can optionally change the lifetime of the new cookie that will be emitted by calling this method;
• invalidate(): Clears all session data and regenerates session ID. Do not use session_destroy();
• getId(): Gets the session ID. Do not use session_id();
• setId(): Sets the session ID. Do not use session_id();
• getName(): Gets the session name. Do not use session_name();
• setName(): Sets the session name. Do not use session_name().

Session attributes

• set(): Sets an attribute by key;
• get(): Gets an attribute by key;
• all(): Gets all attributes as an array of key => value;
• has(): Returns true if the attribute exists;
• replace(): Sets multiple attributes at once: takes a keyed array and sets each key => value pair;
• remove(): Deletes an attribute by key;
• clear(): Clear all attributes.

The attributes are stored internally in a "Bag", a PHP object that acts like an array. A few methods exist for "Bag" management:

• registerBag(): Registers a SessionBagInterface;
• getBag(): Gets a SessionBagInterface by bag name;
• getFlashBag(): Gets the FlashBagInterface. This is just a shortcut for convenience.

Session metadata

• getMetadataBag(): Gets the MetadataBag which contains information about the session.

Session Data Management¶

PHP's session management requires the use of the $_SESSION super-global, however, this interferes somewhat with code testability and encapsulation in an OOP paradigm. To help overcome this, Symfony uses session bags linked to the session to encapsulate a specific dataset of attributes or flash messages.

This approach also mitigates namespace pollution within the $_SESSION super-global because each bag stores all its data under a unique namespace. This allows Symfony to peacefully co-exist with other applications or libraries that might use the $_SESSION super-global and all data remains completely compatible with Symfony's session management.

Symfony provides two kinds of storage bags, with two separate implementations. Everything is written against interfaces so you may extend or create your own bag types if necessary.

SessionBagInterface has the following API which is intended mainly for internal purposes:

• getStorageKey(): Returns the key which the bag will ultimately store its array under in $_SESSION. Generally this value can be left at its default and is for internal use.
• initialize(): This is called internally by Symfony session storage classes to link bag data to the session.
• getName(): Returns the name of the session bag.

Attributes¶

The purpose of the bags implementing the AttributeBagInterface is to handle session attribute storage. This might include things like user ID, and remember me login settings or other user based state information.

• AttributeBag This is the standard default implementation.
• NamespacedAttributeBag This implementation allows for attributes to be stored in a structured namespace.

Any plain key-value storage system is limited in the extent to which complex data can be stored since each key must be unique. You can achieve namespacing by introducing a naming convention to the keys so different parts of your application could operate without clashing. For example, module1.foo and module2.foo. However, sometimes this is not very practical when the attributes data is an array, for example a set of tokens. In this case, managing the array becomes a burden because you have to retrieve the array then process it and store it again:

1
2

$tokens = array('tokens' => array('a' => 'a6c1e0b6',
                                  'b' => 'f4a7b1f3'));

So any processing of this might quickly get ugly, even simply adding a token to the array:

1
2
3

$tokens = $session->get('tokens');
$tokens['c'] = $value;
$session->set('tokens', $tokens);

With structured namespacing, the key can be translated to the array structure like this using a namespace character (defaults to /):

1

$session->set('tokens/c', $value);

This way you can easily access a key within the stored array directly and easily.

AttributeBagInterface has a simple API

• set(): Sets an attribute by key;
• get(): Gets an attribute by key;
• all(): Gets all attributes as an array of key => value;
• has(): Returns true if the attribute exists;
• keys(): Returns an array of stored attribute keys;
• replace(): Sets multiple attributes at once: takes a keyed array and sets each key => value pair.
• remove(): Deletes an attribute by key;
• clear(): Clear the bag;

Flash Messages¶

The purpose of the FlashBagInterface is to provide a way of setting and retrieving messages on a per session basis. The usual workflow would be to set flash messages in a request and to display them after a page redirect. For example, a user submits a form which hits an update controller, and after processing the controller redirects the page to either the updated page or an error page. Flash messages set in the previous page request would be displayed immediately on the subsequent page load for that session. This is however just one application for flash messages.

• AutoExpireFlashBag

  In this implementation, messages set in one page-load will be available for display only on the next page load. These messages will auto expire regardless of if they are retrieved or not.

• FlashBag

  In this implementation, messages will remain in the session until they are explicitly retrieved or cleared. This makes it possible to use ESI caching.

FlashBagInterface has a simple API

• add(): Adds a flash message to the stack of specified type;
• set(): Sets flashes by type; This method conveniently takes both single messages as a string or multiple messages in an array.
• get(): Gets flashes by type and clears those flashes from the bag;
• setAll(): Sets all flashes, accepts a keyed array of arrays type => array(messages);
• all(): Gets all flashes (as a keyed array of arrays) and clears the flashes from the bag;
• peek(): Gets flashes by type (read only);
• peekAll(): Gets all flashes (read only) as keyed array of arrays;
• has(): Returns true if the type exists, false if not;
• keys(): Returns an array of the stored flash types;
• clear(): Clears the bag;

For simple applications it is usually sufficient to have one flash message per type, for example a confirmation notice after a form is submitted. However, flash messages are stored in a keyed array by flash $type which means your application can issue multiple messages for a given type. This allows the API to be used for more complex messaging in your application.

Examples of setting multiple flashes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use Symfony\Component\HttpFoundation\Session\Session;

$session = new Session();
$session->start();

// add flash messages
$session->getFlashBag()->add(
    'warning',
    'Your config file is writable, it should be set read-only'
);
$session->getFlashBag()->add('error', 'Failed to update name');
$session->getFlashBag()->add('error', 'Another error');

Displaying the flash messages might look as follows.

Simple, display one type of message:

1
2
3
4
5
6
7
8
9

// display warnings
foreach ($session->getFlashBag()->get('warning', array()) as $message) {
    echo '<div class="flash-warning">'.$message.'</div>';
}

// display errors
foreach ($session->getFlashBag()->get('error', array()) as $message) {
    echo '<div class="flash-error">'.$message.'</div>';
}

Compact method to process display all flashes at once:

1
2
3
4
5

foreach ($session->getFlashBag()->all() as $type => $messages) {
    foreach ($messages as $message) {
        echo '<div class="flash-'.$type.'">'.$message.'</div>';
    }
}