/
sessions.md
154 lines (115 loc) · 3.89 KB
/
sessions.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
# Sessions
Sessions persist data between requests without passing them to the client and back.
Yii has [a session package](https://github.com/yiisoft/session) to work with session data.
To add it to your application, use composer:
```shell
composer require yiisoft/session --prefer-dist
```
## Configuring middleware
To keep a session between requests, you need to add `SessionMiddleware` to your route group or
application middlewares.
You should prefer a route group 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.
To add a session for a certain group of routes, edit `config/routes.php` like the following:
```php
<?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:
```php
return [
Yiisoft\Yii\Web\Application::class => [
'__construct()' => [
'dispatcher' => DynamicReference::to(static function (Injector $injector) {
return ($injector->make(MiddlewareDispatcher::class))
->withMiddlewares(
[
Router::class,
CsrfMiddleware::class,
SessionMiddleware::class, // <-- add this
ErrorCatcher::class,
]
);
}),
],
],
];
```
## 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();
}
```
## Working with session data
Usually you will use the following methods to work with session data:
```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();
}
```
## Flash messages
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 are what you need.
A flash message is a special type of data, that's 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
}
```
## Custom session storage
When using `Yiisoft\Session\Session`, you can use your own storage implementation:
```php
$handler = new MySessionHandler();
$session = new \Yiisoft\Session\Session([], $handler);
```
Custom storage must implement `\SessionHandlerInterface`.