Yii Session
[](https://packagist.org/packages/yiisoft/session)
[](https://packagist.org/packages/yiisoft/session)
[](https://github.com/yiisoft/session/actions/workflows/build.yml)
[](https://codecov.io/gh/yiisoft/session)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/session/master)
[](https://github.com/yiisoft/session/actions?query=workflow%3A%22static+analysis%22)
[](https://shepherd.dev/github/yiisoft/session)
The package implements a session service, [PSR-15](https://www.php-fig.org/psr/psr-15/) session middleware,
and a flash message service which helps use one-time messages.
## Requirements
- PHP 8.0 - 8.5.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
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
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:
```php
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`.
```php
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:
```php
/** @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
```php
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:
```php
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:
```php
$handler = new MySessionHandler();
$session = new \Yiisoft\Session\Session([], $handler);
```
Custom storage must implement `\SessionHandlerInterface`.
## Documentation
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Session is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)