upscale / swoole-session
PHP sessions compatibility with Swoole web-server
Installs: 5 090
Dependents: 1
Suggesters: 0
Security: 0
Stars: 9
Watchers: 4
Forks: 2
Open Issues: 0
Requires
- php: >=8.0
- upscale/ext-openswoole: ^4.0||^22.0
- upscale/ext-swoole: ^4.0||^5.0
Requires (Dev)
- ext-curl: *
- phpunit/phpunit: ^9.5
- upscale/swoole-launchpad: ^2.0
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:
License
Licensed under the Apache License, Version 2.0.