upscale/swoole-session

PHP sessions compatibility with Swoole web-server

2.1.0 2023-06-12 20:07 UTC

This package is auto-updated.

Last update: 2024-09-28 08:06:22 UTC


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.