Ratchet 0.4.x: a PHP WebSocket server whose event loop is a test matrix, not a decision

The package on Packagist is cboden/ratchet, not ratchetphp

The organisation name and the package name are different things here, and that trips people up on their first install. The recommended way in is Composer, and the requirement string names the package, not the repository:

composer require cboden/ratchet:^0.4.4

That constraint installs the latest supported version, and the README points at CHANGELOG.md for the details of version upgrades, which matters more than usual because the version line has been long. The default branch is itself named 0.4.x, so the branch you would browse for current work is the maintenance line rather than a development branch. The library itself is small: source in src/, tests in tests/, a composer.json, two PHPUnit configuration files, and a Makefile. There is no build step to run before the code is usable, which the Makefile states outright in its own header.

Root access is a stated requirement, not a footnote

The requirements section is the part of this README most likely to change your deployment plan. Shell access is required and root access is recommended. The reason given is concrete: WebSockets requested on port 80 or 443, the latter over SSL, avoid proxy and firewall blockage, and those ports require root access. From there the README gives you two ways out, either put a reverse proxy in front alongside your existing synchronous web stack, or run the two on separate machines. Both add a moving part to an operation that looks like one PHP process, and the server configuration documentation linked from that paragraph is where the specifics live.

That constraint has a second consequence. A long-lived process holding an open socket to every connected client is not the shape of a shared host where you rent a directory and a database, so the deployment options the README describes all assume a machine you control. If your hosting gives you PHP and nothing else, this library is not asking to run there.

The quick example is one class with three callbacks

The demonstration is deliberately small, and it shows the composition idea: a single class implements MessageComponentInterface and the behaviour comes from the callbacks on that interface.

<?php
use Ratchet\MessageComponentInterface;
use Ratchet\ConnectionInterface;
require __DIR__ . '/vendor/autoload.php';
class MyChat implements MessageComponentInterface {
protected $clients;
}

The connection list is an SplObjectStorage, attached on open and used to broadcast an incoming message to everyone except the sender. Running it is a single script, with no server to configure first:

php chat.php

The browser side is three lines of JavaScript, connecting to the echo path on port 8080:

var conn = new WebSocket('ws://localhost:8080/echo');
conn.onmessage = function(e) { console.log(e.data); };
conn.onopen = function(e) { conn.send('Hello Me!'); };

Note the port. The quick example listens on 8080 while the requirements section recommends 80 or 443 for anything real, which is the gap between a demo that starts in thirty seconds and a service that survives a corporate proxy.

Three event loops, three ports, one Autobahn run

The Makefile is where this project's engineering priorities are visible, and it opens by saying it exists to ease the author's development and testing and that users do not need to use make because Ratchet does not need to be compiled. The abtests target then does something more informative: it runs the Autobahn fuzzing server three times in parallel, once per event loop implementation, each on its own port.

ulimit -n 2048 && php tests/autobahn/bin/fuzzingserver.php 8001 LibEvent &
ulimit -n 2048 && php tests/autobahn/bin/fuzzingserver.php 8002 StreamSelect &
ulimit -n 2048 && php tests/autobahn/bin/fuzzingserver.php 8004 LibEv &
wstest -m fuzzingclient -s tests/autobahn/fuzzingclient-all.json

LibEvent, StreamSelect and LibEv are three different ways to wait on sockets, and a library that keeps all three in its test matrix is telling you the event loop is a pluggable choice rather than an assumption baked into the code. The file descriptor limit is raised before each server, which is the practical detail you would otherwise learn about from a refused connection.

The dependency list is written into the documentation target

The apidocs target is worth reading even though almost nobody will run it, because its source paths are an inventory of what Ratchet leans on:

apigen --title Ratchet -d reports/api \
	-s src/ \
	-s vendor/ratchet/rfc6455/src \
	-s vendor/react/event-loop/src \
	-s vendor/react/socket/src \
	-s vendor/react/stream/src

The four vendor paths shown are components under two organisations: ratchet/rfc6455 for the protocol side, and the react family for the event loop, sockets and streams. That is the clearest available description of the architecture, since the README does not draw a diagram or name an architecture at all. Further down the same target reaches for psr/http-message, the Symfony HTTP foundation session and routing components, and evenement, while excluding the Symfony routing tests from the generated docs.

Two targets sit either side of it for the author's own use: test, which is vendor/bin/phpunit, and cover, which adds text and HTML coverage output into a reports directory.

The README opens by asking for help reviving it

Rather than describing features, the first section of this README states a condition. The project is aiming to be revived, to get up to date with the latest versions, and to serve as a starting point for bigger updates to come, and it links a ticket, number 1054, as the place where the ways to help are listed. That framing tells you how to read everything else on the page, including the PHP version line: the library supports running on legacy PHP 5.4 through current PHP 8+, requires no PHP extensions at all as it aims to run on any platform, and recommends the latest supported PHP version, with the revival note pointed at again as the place newer PHP support is being tracked.

The release record is consistent with that. v0.4.2 was published as Sim Phony on 2020-01-28, v0.4.3 on 2020-07-07 and v0.4.4 on 2021-12-14. The last push to the 0.4.x branch was on 2026-06-14, so commits continue while the newest tag is nearly five years old. That is the single fact to weigh before depending on it.

Two PHPUnit configs and a SECURITY file in a small tree

The repository is small enough to take in at a glance, and two entries in it explain the compatibility story better than the README does. There is a phpunit.xml.dist and a phpunit.xml.legacy sitting side by side, which is what a library supporting everything from PHP 5.4 to 8 and newer looks like on disk: one configuration for the modern run and a second for the old toolchain. SECURITY.md is present at the root, so vulnerability reports have a named destination rather than an issue thread.

Elsewhere the tree holds the usual set: a CHANGELOG.md that the install section points you at, a Makefile reserved for the maintainer, composer.json as the dependency manifest, LICENSE for the MIT terms the README names, and .github/ for the workflow definitions. Documentation for users and for the API is not in the tree at all. It lives on the project website, socketo.me, with the server configuration notes on the deploy page and runnable demos kept in a separate examples repository. So the code is here and the explanation is elsewhere, which is worth knowing before you go looking for a docs/ directory.

Editorial conclusion

Take Ratchet when you already run PHP and want a WebSocket endpoint you can assemble from a few interfaces, and you can give it shell access and the root privileges the port 80 or 443 recommendation implies. Pass when you need a version with current PHP support that someone is maintaining, since the newest tag is v0.4.4 from 2021-12-14 and the README still asks for help reviving the project. Before you commit, check the CHANGELOG.md for what the 0.4 series changed, decide whether a reverse proxy or a second machine fits your deployment, and confirm your PHP version is one the project lists rather than one you assume.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ratchetphp/Ratchet on GitHub
4. README
5. Releases