# swow: a C-backed coroutine engine for PHP that installs as a C extension > Swow is a concurrent I/O engine for PHP written with a small C core and most of the surface in PHP. It ships as a PHP extension, installs through PIE or Composer, and its examples directory does more documentation work than the README. **swow/swow** — Coroutine-based cross-platform concurrent I/O engine. - Repository: https://github.com/swow/swow - Stars: 1,329 · Forks: 125 - Language: C - License: Apache-2.0 - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/swow-swow ## A small C core with most of the engine written in PHP Swow describes itself as a multi-platform coroutine-based engine focused on concurrent I/O. The design decision that shapes everything else is stated plainly: the project commits to "using the smallest C core and most of the PHP code", in order to support high performance network programming in PHP. That framing explains what the engine is for. It is not a general purpose async runtime that replaces the PHP process, and it is not a framework with routing and middleware. It is a set of low-level network primitives, coroutine scheduling and channel primitives, exposed to PHP, with the parts that need raw speed and operating system access living in C and the parts that define behaviour living in PHP. The README puts the resulting benefit in terms of secondary development capability: PHP code and the C kernel are integrated so that a developer can extend the engine rather than work around it. The second half of the philosophy is about debugging. The README says the project provides a variety of debugging mechanisms and low-threshold debugging tools, with the stated goal that ordinary developers can debug near the level of experts. That claim is only checkable against the tooling, and the repository layout suggests it is real: there is a `debug` example directory alongside `watchdog`, and static analysis is wired into the build through `phpstan.neon`, `.phan/` and `.php-cs-fixer.dist.php`. ## PIE for a quick install, Composer plus swow-builder for a project The quickest route is PIE, the PHP extension installer, and the README puts it first. The stable channel is one command: ```bash pie install swow/swow-extension ``` A development channel exists alongside it, and the README is candid that it "may contain bugfix" wording that is worth reading closely rather than skimming. The command targets the `dev-develop` branch, which matches the repository's default branch: ```bash pie install swow/swow-extension:dev-develop ``` For a project that manages its dependencies with Composer, the source comes in as a package and a separate builder binary does the compile and install step: ```bash composer require swow/swow ``` ```bash ./vendor/bin/swow-builder --install ``` The `swow-builder` binary lives in the `vendor/bin` directory after the package is pulled in. When the source is updated, the README says to use the `rebuild` option to recompile and then install: ```bash ./vendor/bin/swow-builder --rebuild --install ``` The split matters for CI. Composer alone does not build a C extension, so any pipeline that only runs `composer install` will produce a project without a working extension, and the builder invocation has to be part of the image build or the deployment step. ## Manual installation means a C toolchain and root on UNIX-like systems The README keeps the manual path deliberately short, calling it the "well-known building procedure". Cloning the source is the first step: ```bash git clone https://github.com/swow/swow.git ``` Compiling the extension inside `ext/` uses the standard PHP extension toolchain, and the README asks for root privileges at the install step: ```bash cd swow/ext && \ phpize && ./configure && make && \ sudo make install ``` The `phpize` step means the PHP development headers must be present on the machine, and `sudo make install` writes the built extension into the PHP extension directory. The same output has to be registered with the PHP runtime, which the README does not spell out in the visible text; that part is left to the linked installation documentation. There is a convenient alternative on Windows. The README points to a separate document for manual compilation there, and it also says you can download the DLL directly from the latest release. That is the practical route for Windows developers who do not want a build toolchain at all, and it is the one path in the README that requires no compiler on the host. Note the parenthesis in the README: you can import the project through Composer and then `cd` to `vendor/swow/swow/ext` to install manually, so the manual build does not require a separate clone. ## The examples directory is the real API reference The repository root holds `ext/` for the C extension sources, `lib/` for the library code, `examples/` for runnable samples, `benchmark/` for performance work and `tools/` for supporting scripts. The `examples/` tree is the most informative directory in the project, because it maps the engine's surface area by directory name alone: `amazing.php`, `autoload.php`, and then folders for `buffer`, `channel`, `coroutine`, `debug`, `http_client`, `http_server`, `runtime`, `signal`, `tcp_server`, `watchdog` and `websocket_client`. That list tells you what the engine is actually good for. A `tcp_server` and an `http_server` are the obvious entries, but `websocket_client`, `signal`, `buffer` and `channel` are the primitives that a real service needs, and the presence of `watchdog` says the engine has an opinion about detecting stuck coroutines. A `runtime` example implies you can control the scheduler, which is the sort of thing a coroutine library without runtime control cannot offer. The README itself does not describe any of this. Its documentation section is a set of links: a wiki, a Chinese-language blog, a Chinese-language features page, an API reference, GitHub Discussions and a TODO project. The API reference and the examples are where you learn what the engine does; the README only tells you they exist. The project also carries an `AGENTS.md` at the root and a `CHANGELOG.md`, plus `composer.json`, which makes it usable as a normal Composer package rather than only as a PIE extension. ## The supported matrix is published as badges, not as prose The README encodes the compatibility surface in badge links rather than in sentences. The PHP badge reads 8.0 to 8.5, and the requirements section states PHP 8.0.0 or above with the latest version recommended. The platforms badge lists Win32, GNU/Linux, macOS and FreeBSD, and the requirements text describes the target as common operating systems such as Linux, Windows and macOS, adding that the set is "almost same as libuv" and linking to libuv's supported platforms document. The architecture badge lists x86-64, ARM64, mips64el and riscv64. The mips64el entry is the one worth pausing on, since it points at routers and other small network appliances rather than at servers, and riscv64 points at a newer instruction set. Both suggest the engine is expected to run on constrained hardware, which is consistent with the intent of a small C core. The README also advises using the newest release, and states that the newest release carries the strongest stability and features. That advice sits in tension with the release list itself, where the three most recent tags are v2.0.0-alpha.3, v2.0.0-alpha.2 and v1.7.0-alpha.3. Every recent tag carries an alpha suffix, and the default branch is develop rather than a release branch. In practice, "the newest release" means a pre-release build of a major version. The last push was on 2026-10-12, with v2.0.0-alpha.3 tagged on 2026-10-09, so the v2 line is moving. ## Apache-2.0 for the project, a separate file for everything it bundles Swow is released under the Apache License Version 2.0, and the licence file sits at the repository root. The README adds a qualification that matters for anyone shipping the extension inside a product: Swow "also includes external libraries that are available under a variety of licenses", and points to a file named `LICENSES.full` for the full licence text. That is a standard arrangement, but it is worth reading rather than assuming, because the bundled code covers the C core and its dependencies, and different licences carry different obligations, including attribution requirements and, in some cases, conditions on how the work is distributed. The README does not enumerate which libraries are bundled or what their terms are; it directs you to `LICENSES.full` for that. If your use is commercial redistribution, that file is the input to the review, not the Apache-2.0 grant alone. The project also has a defined security process, and it is a narrow one. Security issues are reported privately by email to `twosee@php.net`, with a stated expectation of a response within 24 hours and a request to follow up if no response arrives. There is no bug bounty, no disclosure policy document and no mention of a security advisory repository in the visible text, so a reporter should treat the email address as the whole channel. ## Where swow is the wrong tool The first wrong case is a shared hosting environment. Swow is a PHP extension with a C core, so it needs control over the PHP runtime and a compiler on the host for anything but the prebuilt Windows DLL. A host where you cannot run `phpize` and `make` puts the project out of reach, and the PIE and Composer paths still compile the extension rather than downloading a ready binary for every platform. The second is a need for stability guarantees. With the default branch set to develop and the recent tags carrying alpha suffixes, teams that pin a version in a production base image are tracking a pre-release line, and the README's own advice to use the newest release does not tell you which artifact to pin. Teams with a change advisory board will need to decide for themselves which tag is acceptable. The third is an application framework need. Swow gives you coroutines, channels, buffers, signals, a watchdog and networking primitives, and then stops. The README has no HTTP router, no ORM, no template layer and no session handling, and the examples are low-level servers rather than applications. If you are choosing between swow and a full stack framework, the question is whether you want a framework at all. Finally, the documentation barrier. The README is a short, mostly Chinese-oriented entry point that links to a wiki, a blog, a features page and an API reference hosted elsewhere. A team without Chinese language reading available will be relying on the English wiki and API reference plus the examples directory, and the README's own feature explanation is written in a promotional register that says less than the sample code does. ## Conclusion Adopt swow if you are writing PHP network code that needs coroutines, channels and a watchdog, and you are willing to compile a C extension into your PHP runtime. Do not adopt it if you need a stable 1.x release to pin, since the newest tags are v2.0.0 alpha builds and the default branch is develop. Before you install, confirm that your PHP version falls between 8.0 and 8.5 and that your platform and CPU are on the published list, then read the licence file at LICENSES.full because the Apache-2.0 grant covers the project code while the bundled external libraries carry their own terms. ## FAQ ### How do I install the swow PHP extension? The README lists four routes. PIE installs the prebuilt extension with `pie install swow/swow-extension`, Composer requires the `swow/swow` package and then runs `./vendor/bin/swow-builder --install`, UNIX-like systems can build it from source with `phpize && ./configure && make && sudo make install` inside `ext/`, and Windows users can download the DLL from the latest release page. ### What PHP versions and platforms does swow support? The requirements section asks for PHP 8.0.0 or above with the latest version recommended, and the badges list PHP 8.0 to 8.5, the platforms Win32, GNU/Linux, macOS and FreeBSD, and the architectures x86-64, ARM64, mips64el and riscv64. ### What is swow-builder used for? It is the automatic installer that ships in the `vendor/bin` directory after you run `composer require swow/swow`. The `--install` option compiles and installs the extension, and the README says to use `--rebuild --install` after updating the source code. ### How should I report a security issue in swow? The README says to report it privately by email to `twosee@php.net`, and states that you should receive a response within 24 hours, with a request to follow up by email if you do not. ## Sources - [Issues](https://github.com/swow/swow/issues) - [License: Apache-2.0](https://github.com/swow/swow/blob/develop/LICENSE) - [README](https://github.com/swow/swow/blob/develop/README.md) - [Releases](https://github.com/swow/swow/releases) - [swow/swow on GitHub](https://github.com/swow/swow) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/swow-swow