yiisoft/session

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

Requires

• php: ^7.4|^8.0
• psr/http-message: ^1.0
• psr/http-message-implementation: 1.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• yiisoft/cookies: ^1.0

Requires (Dev)

• nyholm/psr7: ^1.4
• phpunit/phpunit: ^9.5
• roave/infection-static-analysis-plugin: ^1.16
• spatie/phpunit-watcher: ^1.23
• vimeo/psalm: ^4.30|^5.6
• yiisoft/di: ^1.1

BSD-3-Clause

• middleware
• session
• flash
• psr-15

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 --prefer-dist

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.

Support the project

Follow updates