Sessions

Store and retrieve data associated with a user's browsing session.

Overview

The Drupal session management subsystem is built on top of the Symfony session component. It is optimized in order to minimize the impact of anonymous sessions on caching proxies. A session is only started if necessary and the session cookie is removed from the browser as soon as the session has no data. For this reason it is important for contributed and custom code to remove session data if it is not used anymore.

Usage

Session data is accessed via the \Symfony\Component\HttpFoundation\Request::getSession() method, which returns an instance of \Symfony\Component\HttpFoundation\Session\SessionInterface. The most important methods on SessionInterface are set(), get(), and remove().

The following code fragment shows the implementation of a counter controller relying on the session:

public function counter(Request $request) {
  $session = $request->getSession();
  $count = $session->get('mymodule.counter', 0) + 1;
  $session->set('mymodule.counter', $count);

  return [
    '#markup' => $this->t('Page Views: @count', ['@count' => $count]),
    '#cache' => [
      'max-age' => 0,
    ],
  ];
}

public function reset(Request $request) {
  $session = $request->getSession();
  $session->remove('mymodule.counter');
}

It is important to keep the amount of data stored inside the session to a minimum, as the complete session is loaded on every request. Also third party session storage backends do not necessarily allow objects of unlimited size. If it is necessary to collect a non-trivial amount of data specific to a user's session, use the Key/Value store to save the serialized data and only store the key to the entry in the session.

Reserved attributes and namespacing

Contributed modules relying on the session are encouraged to namespace session attributes by prefixing them with their project name or an abbreviation thereof.

Some attributes are reserved for Drupal core and must not be accessed from within contributed and custom code. Reserved attributes include:

• uid: The user ID for an authenticated user. The value of this attribute cannot be modified.

Custom session bags

Modules can register custom session bags in order to provide type safe interfaces on module specific session data. A session bag must implement \Symfony\Component\HttpFoundation\Session\SessionBagInterface. Custom session bags are registered using a service entry tagged with the session_bag service tag. Custom session bags can be accessed through the session retrieved from the request object.

Example service definition:

session_test.session_bag:
  class: Drupal\session_test\Session\TestSessionBag
  tags:
    - { name: session_bag }

Example of accessing a custom session bag:

$bag = $request->getSession()
    ->getBag(TestSessionBag::BAG_NAME);
$bag->setFlag();

Session data must be deleted from custom session bags as soon as it is no longer needed (see Overview above).

Parent topics

File

core/core.api.php, line 2630