README

This library implements compatibility of native PHP sessions with Swoole / Open Swoole web-server.

Features:

• Transparent session start/stop
• Session ID in cookies or query string
• Native or custom session ID generator
• Automatic session data persistence
• Compliance with PHP session configuration

Installation

The library is to be installed via Composer as a dependency:

composer require upscale/swoole-session

Usage

Wrap your request handling middleware into the session decorator:

require 'vendor/autoload.php';

use Upscale\Swoole\Session\SessionDecorator;

$server = new \Swoole\Http\Server('127.0.0.1', 8080);
$server->set([
    // Disable coroutines to safely access $_SESSION
    'enable_coroutine' => false,
]);
$server->on('request', new SessionDecorator(function ($request, $response) {
    $_SESSION['data'] ??= rand();
    $response->end($_SESSION['data']);
}));

$server->start();

Limitations

Coroutines

PHP sessions rely on the superglobal variable $_SESSION making them incompatible with the Swoole coroutines. When a request idles for an asynchronous I/O operation, its worker process is reused to handle other request(s). Swoole switches the call stack context, but the superglobals stay in memory shared across coroutines/requests. Session data loaded for one request leaks to other requests causing all sorts of data integrity issues.

Disable coroutines to safely use the PHP sessions:

$server->set([
    'enable_coroutine' => false,
]);

Output

Direct output bypassing the response instance \Swoole\Http\Response is prohibited in the Swoole environment. Writing to the standard output stream violates the headers_sent requirement of the PHP session functions:

PHP Warning: session_start(): Cannot start session when headers already sent

Statements that "send headers" and hinder the sessions:

• echo/print
• fwrite(STDOUT)
• file_put_contents('php://stdout')
• include 'template.phtml'
• header()
• setcookie/setrawcookie()
• etc.

Output buffering commonly used by template engines avoids this pitfall, for example:

ob_start();
include $templatePhtml;
$output = ob_get_clean();

$response->end($output);

Warning! Coroutines used to "send headers" despite the output buffering until this has been fixed in Swoole 4.5.3. This is not a problem since coroutines have to be disabled for the data integrity reasons discussed above.

Blocking

Concurrent requests are prone to the session write race conditions. The default file-based session storage of PHP employs the filesystem locking to avoid the data corruption. Requests of the same session ID execute sequentially blocking their respective worker processes from session_start() until session_write_close().

Asynchronous coroutine-aware libraries built specifically for Swoole:

• itxiao6/session
• swoft-cloud/swoft-session

License

Licensed under the Apache License, Version 2.0.