Swoole: coroutine concurrency for PHP, installed as a C extension

The PHP problem Swoole is aimed at

A conventional PHP-FPM worker handles one request at a time and blocks on every network call inside it. A handler that fetches two URLs sequentially spends most of its wall time waiting, and the usual fix is more workers, which means more memory per process. Swoole attacks the waiting directly: it runs an event loop over epoll or kqueue and schedules many coroutines inside a single process, so a handler that waits on I/O yields instead of occupying a worker. The README describes the project as an "event-driven, asynchronous, coroutine-based concurrency library with high performance for PHP" and states that the network layer takes advantage of the underlying epoll/kqueue implementation. The audience is therefore PHP teams that already run their own servers and can change the runtime, not people on shared hosting. It also suits teams that want to keep writing ordinary synchronous PHP: the README says developers can use fully synchronized code to get asynchronous performance, with the coroutine scheduling done by the extension rather than by new language keywords.

How the coroutine scheduler and runtime hook work

Two mechanisms carry the design. The first is the coroutine scheduler: go() or Co\go() creates a coroutine, Co\run() starts a scheduler, and the extension suspends a coroutine when it hits a hooked I/O call and resumes it when the underlying file descriptor is ready. The README compares coroutines to ultra-lightweight threads and says thousands can run in a single process. The second is the runtime hook, which the README describes as hooking PHP's blocking I/O functions at the bottom layer and automatically converting them to non-blocking functions. That is what makes existing code cooperative: ext-curl, ext-redis, ext-mysqli, the pdo_mysql, pdo_pgsql, pdo_sqlite, pdo_oracle and pdo_odbc drivers, stream functions over TCP, UDP, UDG, Unix, SSL/TLS, the filesystem and pipes, ext-sockets, ext-soap, sleep and usleep, proc_open, gethostbyname, shell_exec, exec, and fread, fopen, fsockopen, fwrite and flock are all on the supported list. The hook is opt-in per server through hook_flags with SWOOLE_HOOK_ALL in the HTTP example. The list is also the boundary of the design: anything not on it is not converted, and a blocking call inside a coroutine holds the scheduler until it returns.

Installing Swoole and running a first coroutine server

The README's Quick Start points at the phpswoole/swoole Docker image rather than at a source build. The command it gives prints the extension information, and the output should show a Swoole section with the version and enabled options.

docker run --rm phpswoole/swoole "php --ri swoole"

The README links to the docker-swoole repository for details on using the image. For a source install, the repository is a PHP extension: config.m4 and config.w32 sit at the top level alongside CMakeLists.txt, and the Dockerfile in the repository shows the shape of a build. It copies the checkout into ext/swoole inside a PHP source tree, runs buildconf and configure with --enable-swoole, and adds the optional feature flags --enable-swoole-curl, --enable-swoole-pgsql, --enable-swoole-sqlite, --enable-cares, --with-swoole-odbc=unixODBC,/usr and --enable-brotli. That file is built for a debug and AddressSanitizer environment, so treat it as a description of the configure surface, not as a production recipe.

Once the extension is loaded, the smallest real service is the HTTP server from the README. It listens on 127.0.0.1 port 9501, enables the runtime hook, and runs two coroutines that fetch two URLs concurrently with Co::join, then returns the results as JSON.

$http = new Swoole\Http\Server('127.0.0.1', 9501);
$http->set(['hook_flags' => SWOOLE_HOOK_ALL]);

$http->on('request', function ($request, $response) {
    $result = [];
    Co::join([
        go(function () use (&$result) {
            $result['google'] = file_get_contents("https://www.google.com/");
        }),
        go(function () use (&$result) {
            $result['taobao'] = file_get_contents("https://www.taobao.com/");
        })
    ]);
    $response->end(json_encode($result));
});

$http->start();

Run that file with the PHP binary that has the extension loaded and request the port. The two fetches overlap because file_get_contents is hooked, and the response is a JSON object with a google and a taobao key. The README's concurrency example shows the same idea with a TCP client, a TCP server, a Redis subscriber and a Redis publisher as four coroutines inside Co\run, which is a useful second test because it exercises stream sockets and ext-redis together.

Where Swoole stops being the right choice

The hook list is the honest limitation. If your hot path calls an extension that is not on it, that call blocks the whole scheduler for the duration, and coroutine concurrency degrades toward sequential execution while still paying the complexity of a long-running process. The README's own list is long but finite, and the repository's examples directory is organised by feature (http, http2, curl, postgresql, socket_coro, ssl, task and others), which tells you the surface is broad but also that each path has its own behaviour to learn. A second constraint is platform. The README's Quick Start is Docker, the repository Dockerfile targets ubuntu:22.04, and the search terms around a Swoole Windows build and a swoole dll download point at a demand the README does not satisfy: nothing there documents a Windows build. Third, this is a C++ extension, so the deployment unit changes. You need a PHP build that includes it, which rules out environments where you cannot install extensions or where the PHP binary is managed by someone else. Finally, a long-running coroutine server keeps state between requests, so anything you relied on PHP-FPM to reset per request (globals, static caches, open handles) becomes your responsibility. The README does not document rollback or a gradual migration path, so plan the cutover yourself.

Swoole against OpenSwoole and against plain PHP-FPM

The related searches include Open Swoole, and the difference is organisational as much as technical. OpenSwoole is a fork of this codebase; the two share the coroutine and event-loop model and the same style of hooked I/O, so the choice between them is mainly about which project's release cadence and community you want to track, not about a different concurrency design. The comparison that changes your architecture is Swoole against PHP-FPM. PHP-FPM gives you process isolation per request and a runtime you almost certainly already have; Swoole gives you many concurrent I/O operations per process and a resident event loop you must operate. If your workload is CPU-bound, or your handlers do not wait on the network much, PHP-FPM with more workers is simpler and the coroutine machinery buys you little. Swoole pays off when handlers are I/O-bound and you want to keep the synchronous style. The repository also points at Swoole Compiler in the search terms, which is a separate product from this extension; nothing in the README describes bytecode compilation, so do not read the two as one thing.

Maintenance, release cadence and the licence

The repository is not archived, and the last push was on 2026-09-15. Recent releases listed are v6.1.10 on 2026-09-15, v6.2.2 on 2026-07-08 and v6.1.9 on 2026-07-07, so two release lines are being published in parallel. That matters for upgrades: you have to decide whether to follow 6.1.x or 6.2.x, and the release notes do not state which line is the long-term one. Upgrading a C++ extension is not a package-manager bump. You rebuild against a specific PHP version, and the repository Dockerfile pins PHP_VERSION to 8.2.28 as a build argument, which is a reminder that the extension is compiled into or alongside one PHP build. Budget for a rebuild and a retest whenever PHP or Swoole moves. The licence is Apache-2.0, per the repository metadata and the LICENSE file at the top level, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve notices and state changes. That is a summary of the licence text, not legal advice, and if you redistribute a modified extension you should read the LICENSE file in full. Note that Swoole Compiler is a separate product with its own terms, which this licence does not cover.

Editorial conclusion

Adopt Swoole when you control the PHP runtime and your bottleneck is blocking I/O: MySQL, Redis, cURL or stream sockets called inside request handlers. Do not adopt it when you cannot compile or install a PHP extension, when the target is Windows, or when you depend on extensions outside the hook list, because those calls stay blocking and will stall the coroutine scheduler. Before committing, verify three things on your own stack: that php --ri swoole reports the build you expect, that your framework integration is listed in Awesome Swoole, and that every blocking call in your hot path appears in the Runtime Hook list. If an extension you rely on is missing from that list, Swoole is the wrong tool for that service.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. swoole/swoole-src on GitHub