PHP sessions compatibility with Swoole web-server

2.1.0 2023-06-12 20:07 UTC

This package is auto-updated.

Last update: 2023-09-12 20:56:58 UTC


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


  • 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


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

composer require upscale/swoole-session


Wrap your request handling middleware into the session decorator:

require 'vendor/autoload.php';

use Upscale\Swoole\Session\SessionDecorator;

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




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:

    'enable_coroutine' => false,


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:

include $templatePhtml;
$output = ob_get_clean();


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.


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:


Licensed under the Apache License, Version 2.0.