README

Yii Session

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

Requirements

PHP 8.0 or higher.

Installation

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:

<?php

declare(strict_types=1);

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

return [
    Group::create('/blog')
        ->middleware(SessionMiddleware::class)
        ->routes(
            // ...
        )
];

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))
                    ->withMiddlewares(
                        [
                            ErrorCatcher::class,
                            SessionMiddleware::class, // <-- add this
                            CsrfMiddleware::class,
                            Router::class,
                        ]
                    );
            }),
        ],
    ],
];

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
    $session->remove('lastAccessTime');

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

    // clear session data from runtime
    $session->clear();
}

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
    $session->open();

    // work with session

    // write session values and then close it
    $session->close();
}

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
    $session->discard();

    // destroy session completely
    $session->destroy();    
}

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.

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

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

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

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

./vendor/bin/psalm

License

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.

yiisoft / session

Maintainers

Details