PHPackages                             upscale/swoole-session - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. upscale/swoole-session

ActiveLibrary[DevOps & Deployment](/categories/devops)

upscale/swoole-session
======================

PHP sessions compatibility with Swoole web-server

2.1.0(3y ago)95.7k↓91.1%2Apache-2.0PHPPHP >=8.0CI failing

Since Sep 25Pushed 2y ago3 watchersCompare

[ Source](https://github.com/upscalesoftware/swoole-session)[ Packagist](https://packagist.org/packages/upscale/swoole-session)[ Docs](https://github.com/upscalesoftware/swoole-session)[ RSS](/packages/upscale-swoole-session/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (4)Versions (7)Used By (0)

PHP Sessions for Swoole [![Build Status](https://github.com/upscalesoftware/swoole-session/workflows/Tests/badge.svg?branch=master)](https://github.com/upscalesoftware/swoole-session/actions?query=workflow%3ATests+branch%3Amaster)
======================================================================================================================================================================================================================================

[](#php-sessions-for-swoole-)

This library implements compatibility of native [PHP sessions](http://us3.php.net/manual/en/book.session.php) with [Swoole](https://github.com/swoole/swoole-src) / [Open Swoole](https://github.com/openswoole/swoole-src) 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](http://us3.php.net/manual/en/session.configuration.php)

Installation
------------

[](#installation)

The library is to be installed via [Composer](https://getcomposer.org/) as a dependency:

```
composer require upscale/swoole-session
```

Usage
-----

[](#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
-----------

[](#limitations)

### Coroutines

[](#coroutines)

PHP sessions rely on the superglobal variable `$_SESSION` making them incompatible with the Swoole [coroutines](https://www.swoole.co.uk/coroutine). 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

[](#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](http://us3.php.net/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](https://www.php.net/manual/en/book.outcontrol.php) 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](https://github.com/swoole/swoole-src/pull/3571) in Swoole 4.5.3. This is not a problem since coroutines have to be disabled for the data integrity reasons discussed above.

### Blocking

[](#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](https://github.com/itxiao6/session)
- [swoft-cloud/swoft-session](https://github.com/swoft-cloud/swoft-session)

License
-------

[](#license)

Licensed under the [Apache License, Version 2.0](https://github.com/upscalesoftware/swoole-session/blob/master/LICENSE.txt).

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity26

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~344 days

Recently: every ~429 days

Total

6

Last Release

1117d ago

Major Versions

1.1.0 → 2.0.02022-11-22

PHP version history (3 changes)1.0.0PHP ^7.1.0

1.1.0PHP >=7.1

2.0.0PHP >=8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6521759?v=4)[Upscale Software](/maintainers/upscalesoftware)[@upscalesoftware](https://github.com/upscalesoftware)

---

Top Contributors

[![sshymko](https://avatars.githubusercontent.com/u/1231423?v=4)](https://github.com/sshymko "sshymko (36 commits)")

---

Tags

compatibilityphpserverswoolesession

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/upscale-swoole-session/health.svg)

```
[![Health](https://phpackages.com/badges/upscale-swoole-session/health.svg)](https://phpackages.com/packages/upscale-swoole-session)
```

###  Alternatives

[swoole-bundle/swoole-bundle

Open/Swoole Symfony Bundle

7262.8k](/packages/swoole-bundle-swoole-bundle)[felixfbecker/language-server-protocol

PHP classes for the Language Server Protocol

22581.4M5](/packages/felixfbecker-language-server-protocol)[php-mcp/server

PHP SDK for building Model Context Protocol (MCP) servers - Create MCP tools, resources, and prompts

850577.8k55](/packages/php-mcp-server)[tmtbe/swooledistributed

In order to develop the api server

1.4k9.5k1](/packages/tmtbe-swooledistributed)[renoki-co/laravel-healthchecks

Laravel Healthchecks is a simple controller class that helps you build your own healthchecks endpoint without issues.

5755.0k](/packages/renoki-co-laravel-healthchecks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)