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 7.4 or higher.
Installation
The package could be installed with composer:
composer require yiisoft/session --prefer-distIn 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/phpunitMutation testing
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-pluginStatic analysis
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalmLicense
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
