Initialize Session Middleware

The BabDev\WebSocket\Server\Session\Middleware\InitializeSession class is a server middleware which reads the session data from the web-facing frontend of your application.

This middleware requires the session classes from Symfony's HttpFoundation component and will store the initialized session to the connection's attribute store.

Please see the Symfony documentation for more information on how to use their API.

Creating the Middleware

The middleware requires two arguments; the decorated middleware and a session factory.

<?php declare(strict_types=1);

use BabDev\WebSocket\Server\Session\Middleware\InitializeSession;
use BabDev\WebSocket\Server\Session\SessionFactory;
use BabDev\WebSocket\Server\Session\Storage\ReadOnlyNativeSessionStorageFactory;

$middleware = new InitializeSession(
    $decoratedMiddleware,
    new SessionFactory(new ReadOnlyNativeSessionStorageFactory()),
);

Accessing the Session

To access the session, you can retrieve it using the "session" key from the connection's attribute store.

$session = $connection->getAttributeStore()->get('session');

Session ID Validation

The session ID is read from the session cookie sent by the client, so it is validated before any session data is read when using the BabDev\WebSocket\Server\Session\Storage\ReadOnlyNativeSessionStorage class. The session is started without any data (as if the client had no session) when:

• The request does not include a session cookie
• The session ID does not have the format of a session ID generated by PHP (22 to 250 characters from a-z, A-Z, 0-9, ,, and -)
• The session.use_strict_mode option is enabled (the default for this storage) and the save handler rejects the session ID, such as when no session exists for the ID

If the save handler fails to read the session data, a BabDev\WebSocket\Server\Session\Exception\InvalidSession exception is thrown and the connection is closed with a 500 Internal Server Error response.

As the session is read-only, the session handler used by the storage does not allow the session data to be written, destroyed, or garbage collected; a BabDev\WebSocket\Server\Session\Exception\ReadOnlySession exception is thrown if this is attempted.

Position in Middleware Stack

It is recommended that this middleware is decorated by the BabDev\WebSocket\Server\Http\Middleware\ParseHttpRequest middleware in your application (see the message flow section from the architecture documentation to see the recommended stack with all optional middleware), however it can be placed anywhere after the HTTP request has been parsed and does not expect one of the server middleware sub-interfaces.

It is also recommended that this middleware decorates the BabDev\WebSocket\Server\WebSocket\Middleware\EstablishWebSocketConnection middleware, but it can decorate any server middleware.