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.
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,
]
);
}),
],
],
];
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
}
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();
}
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
.
The package is tested with PHPUnit. To run tests:
./vendor/bin/phpunit
The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:
./vendor/bin/roave-infection-static-analysis-plugin
The code is statically analyzed with Psalm. To run static analysis:
./vendor/bin/psalm
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.