yiisoft / session
A session service, PSR-15 session middleware, and a flash message service which helps use one-time messages.
Fund package maintenance!
Opencollective
yiisoft
Installs: 148 467
Dependents: 26
Suggesters: 0
Security: 0
Stars: 14
Watchers: 14
Forks: 7
Open Issues: 2
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
This package is auto-updated.
Last update: 2023-09-18 06:42:09 UTC
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.