A session service, PSR-15 session middleware, and a flash message service which helps use one-time messages.

2.0.0 2023-02-13 17:36 UTC



Yii Session

Latest Stable Version Total Downloads Build status Code Coverage Mutation testing badge static analysis type-coverage

The package implements a session service, PSR-15 session middleware, and a flash message service which helps use one-time messages.


  • PHP 8.0 or higher.


The package could be installed with composer:

composer require yiisoft/session

In order to maintain a session between requests you need to add SessionMiddleware to your route group or application middlewares. Route group should be preferred when you have both API with token-based authentication and regular web routes in the same application. Having it this way avoids starting the session for API endpoints.

Yii 3 configuration

In order to add a session for a certain group of routes, edit config/routes.php like the following:



use Yiisoft\Router\Group;
use Yiisoft\Session\SessionMiddleware;

return [
            // ...

To add a session to the whole application, edit config/application.php like the following:

return [
    Yiisoft\Yii\Http\Application::class => [
        '__construct()' => [
            'dispatcher' => DynamicReference::to(static function (Injector $injector) {
                return ($injector->make(MiddlewareDispatcher::class))
                            SessionMiddleware::class, // <-- add this

General usage

You can access session data through SessionInterface.

public function actionProfile(\Yiisoft\Session\SessionInterface $session)
    // get a value
    $lastAccessTime = $session->get('lastAccessTime');

    // get all values
    $sessionData = $session->all();
    // set a value
    $session->set('lastAccessTime', time());

    // check if value exists
    if ($session->has('lastAccessTime')) {
        // ...    
    // remove value

    // get value and then remove it
    $sessionData = $session->pull('lastAccessTime');

    // clear session data from runtime

In case you need some data to remain in session until read, such as in case with displaying a message on the next page flash messages is what you need. A flash message is a special type of data, that is available only in the current request and the next request. After that, it will be deleted automatically.

FlashInteface usage is the following:

/** @var Yiisoft\Session\Flash\FlashInterface $flash */

// request 1
$flash->set('warning', 'Oh no, not again.');

// request 2
$warning = $flash->get('warning');
if ($warning !== null) {
    // do something with it

Opening and closing session

public function actionProfile(\Yiisoft\Session\SessionInterface $session)
    // start session if it's not yet started

    // work with session

    // write session values and then close it

Note: Closing session as early as possible is a good practice since many session implementations are blocking other requests while session is open.

There are two more ways to close session:

public function actionProfile(\Yiisoft\Session\SessionInterface $session)
    // discard changes and close session

    // destroy session completely

Custom session storage

When using Yiisoft\Session\Session as session component, you can provide your own storage implementation:

$handler = new MySessionHandler();
$session = new \Yiisoft\Session\Session([], $handler);

Custom storage must implement \SessionHandlerInterface.


Unit testing

The package is tested with PHPUnit. To run tests:


Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:


Static analysis

The code is statically analyzed with Psalm. To run static analysis:



The Yii Session is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack