Session & Cookies
Windwalker manages sessions itself. It does not use PHP's native session_start() by default. The session is created by the Session object, which stores its data through a handler and reads and writes it through a bridge. Cookies are handled by a separate CookiesInterface.
Session Configuration
Session settings live in etc/packages/session.config.php:
return #[
ConfigModule(
name: 'session',
enabled: true,
priority: 100,
belongsTo: SessionPackage::class,
)
]
static fn() => [
'default' => env('SESSION_DEFAULT') ?: 'filesystem',
'cookie_params' => [
'expires' => '+150minutes',
'path' => '/',
'domain' => null,
'secure' => false,
'httponly' => true,
'samesite' => CookiesInterface::SAMESITE_LAX,
],
'session_options' => [
'name' => 'WINDWALKER_SESSID',
'use_cookies' => '0',
'gc_divisor' => '1000',
'gc_probability' => env('SESSION_GC_PROBABILITY', '1'),
],
'ini' => [
'use_cookies' => '0',
'gc_divisor' => '1000',
'gc_probability' => env('SESSION_GC_PROBABILITY', '1'),
],
];default: the profile to use. The built-in profiles arefilesystem,native,databaseandnull, defined underfactories.instances.cookie_params: expiry, path, domain, secure, httponly and samesite of the session cookie.expiresaccepts a relative time such as+150minutes.session_options: the session name and PHP session options.ini: PHP ini values applied to the session.
Handlers and Bridges
A handler decides where session data is stored. The built-in handlers are:
arraynullnativedatabasefilesystemredis
A bridge decides how the session is connected to the request. The bridges are php (PhpBridge, the Windwalker implementation) and native.
Each profile in factories.instances builds a session from a bridge, a handler and a cookies driver. To switch handler, change the profile name in default, or edit the profile:
'instances' => [
'database' => static fn () => SessionFactory::createSession(
'php',
'database',
'request',
[
SessionInterface::OPTION_AUTO_COMMIT => true,
]
),
],The handler class for each name is set under factories.handlers:
'handlers' => [
'database' => static fn() => create(
DatabaseHandler::class,
options: [
'table' => 'sessions',
]
),
],TIP
DatabaseHandler uses the table windwalker_sessions by default. The config above sets it to sessions. Create that table with a migration.
Database Handler
Use the database handler when sessions must be shared across several servers. Keep the table in the same database as the application data.
Redis Handler
Use the redis handler for fast shared sessions. The default key prefix is ww_sess_. The config maps it with RedisHandler::class:
'handlers' => [
'redis' => RedisHandler::class,
],Using the Session
Inject Session into a constructor, or get it from the container:
use Windwalker\Session\Session;
class CheckoutController
{
public function __construct(
protected Session $session,
) {
}
public function save(): void
{
$this->session->start();
$this->session->set('cart_id', 'c-1001');
$cartId = $this->session->get('cart_id');
$id = $this->session->getId();
}
}Use start() and stop() to open and close the session. The session stops automatically when the response is sent.
Call stop() yourself when you need the data saved before the response ends, for example before a long task. stop() writes the data to the handler and closes the session:
$session->set('cart_id', 'c-1001');
// Save now, while the rest of the request keeps running
$session->stop();
$this->sendConfirmationMail();TIP
Changes made after stop() are not saved. Call start() again to keep using the session.
Flash Messages
Flash messages are kept until the next request reads them:
// Add a message in the current request
$app->addMessage('Saved successfully.', 'success');
// Read messages of one type
$messages = $app->getMessages('success');AppContext::addMessage() and getMessages() wrap the flash storage. Pass true as the $peek argument of getMessages() to read without clearing the messages.
WARNING
Call getMessages() after the session has started. Before start(), the session is empty, so the call returns nothing.
$session->start();
// Read without clearing, so the message stays for the next request
$messages = $app->getMessages('success', true);Robots
Bots and crawlers do not need a session. The web application registers a shared BrowserNext object, built from the request headers. Its isRobot() method returns true for bot and robot devices. SessionRobotSubscriber listens to BeforeRequestEvent. When the visitor is a robot and a Session exists, it sets session.default to the null profile, so the session writes nothing to storage.
Your code does not need to check the robot. Inject Session as usual:
use Windwalker\Session\Session;
class ProductController
{
public function show(Session $session): void
{
// A robot's request writes to the null profile and is discarded
$session->set('last_viewed', 'p-100');
}
}To branch on the visitor, inject BrowserNext and call isRobot():
use Windwalker\Core\Http\BrowserNext;
class SitemapController
{
public function index(BrowserNext $browser): string
{
if ($browser->isRobot()) {
return $this->renderPlainSitemap();
}
return $this->renderInteractiveSitemap();
}
}INFO
The robot switch only runs when the BrowserNext service exists. Without it, every visitor gets a session.
Destroy, Regenerate and Fork
regenerate()changes the session ID and sends a new cookie. Call it after login to prevent session fixation.destroy()clears the session data and the cookie.fork($newId)copies the current session to a new ID. It needs an active session, and it throwsLogicExceptionwith the native bridge.
// After successful login
$session->regenerate();
// Log out
$session->destroy();Switching to a Known Session ID
setId() sets the ID the session uses. Use fork() to copy the current session data into a new ID instead.
Call setId() before start(). If the session is already running, call stop() first, then setId(), then start(). Otherwise the new ID has no effect.
$session->stop();
$session->setId($newId);
$session->start();WARNING
Accepting a session ID from the request lets an attacker choose a victim's session. Only call setId() with an ID that your application created and stored itself.
Cookies
Cookies use the CookiesInterface. Two implementations are available:
request: reads the cookies of the request. Writes are added to the response.native: uses PHP's cookie functions.
Inject CookiesInterface to use it:
use Windwalker\Session\Cookie\CookiesInterface;
class PreferenceController
{
public function __construct(
protected CookiesInterface $cookies,
) {
}
public function save(): void
{
$this->cookies->set('theme', 'dark');
$theme = $this->cookies->get('theme');
$this->cookies->remove('theme');
}
}Cookie options come from CookiesOptions: path, domain, secure, httpOnly and sameSite. CookiesAutoSecureSubscriber sets secure to true on HTTPS requests when COOKIES_AUTO_SECURE is enabled.
Cookies and Session Together
The session ID is sent in a cookie. The session data stays on the server. Do not store a session's secret data in a cookie.
TIP
Store only small, non-sensitive values in cookies, such as a locale or a UI preference. Store user identity and private data in the session.
WARNING
Cookies can be edited by the user. Never trust a value read from a cookie without validating it.