Since 2021 I've been using phpsocket.io in production. It came in to replace a legacy Node.js server. I started as a user, began contributing to the project and, over time, was invited to become one of its maintainers. It's the most used Socket.IO package in the PHP ecosystem, but it has a limitation that matters more every year: it only speaks the old protocol, so it only works with socket.io-client 1.x and 2.x. It also stays on Workerman 4, because Workerman 5 requires PHP 8.1 and the package still serves people on PHP 7.4.
To solve that, I built socket.io-server, a Socket.IO v4 server for PHP, built on Workerman, a PHP framework for asynchronous network servers that runs as its own process, outside PHP-FPM. It works with the official socket.io-client v3 and v4, follows an API close to phpsocket.io's and, with OPcache and the JIT on, gets close to the official Node.js server while using less memory.
The package is at version 0.x and ready to use. If you need Socket.IO v4 in PHP, or want to move off the 2.x client, give it a try and let me know how it goes: feedback, issues and pull requests are very welcome.
Table of contents
- Socket.IO vs WebSocket: what's the difference?
- Why phpsocket.io doesn't work with socket.io-client v3 and v4
- Why a new package
- What it does
- Performance against the official server
- Continuous load test without leaking memory
- Building it with AI
- Current state and next steps
- Conclusion
- FAQ
Socket.IO vs WebSocket: what's the difference?
WebSocket is a standard web protocol that keeps a connection open between client and server, so both can send messages at any time, without the client having to keep asking. But that's all it gives you: loose messages, text or binary. Reconnecting, knowing which answer belongs to which question, sending to a group of users, it's all up to you.
Socket.IO was born in 2010 as a library for Node.js, and the official server is still in Node. Its protocol is documented, which makes it possible to implement servers and clients in other languages, such as Java, Python and Rust.
It isn't an alternative to WebSocket: it uses WebSocket as a transport and adds what's missing on top. That means named events (emit and on), answers through callbacks (acknowledgements), rooms to send messages to groups, automatic reconnection and a fallback to HTTP long-polling (HTTP requests that stay open until there's something to answer) when a proxy or firewall blocks WebSocket. Since it has its own protocol, a Socket.IO client can't talk to a plain WebSocket server, or the other way around: the server has to speak Socket.IO too, and the right version of it.
Why phpsocket.io doesn't work with socket.io-client v3 and v4
Socket.IO has two layers. At the bottom is Engine.IO, which handles the connection: it opens over HTTP long-polling, upgrades to WebSocket when it can and keeps the heartbeat going. On top is Socket.IO, with events, namespaces, rooms and acknowledgements.
In Socket.IO 3.0, released in 2020, both layers changed protocol: Engine.IO went to v4 and Socket.IO to v5. And the change is incompatible both ways. By default, a 2.x client can't connect to a v4 server (the official Node server has the allowEIO3 option to accept old clients during a migration), and a v3 or v4 client can't connect to an old server.
phpsocket.io implements the old protocol (Engine.IO v3). In practice, anyone using PHP on the server is stuck with the 2.x line of the JavaScript client, which stopped getting new features in 2020 (its last version, 2.5.0, is from 2022), without what came after, such as connection state recovery.
Why a new package
Today there's no PHP server for Socket.IO v4 on the site's official list of implementations. The other known package, hyperf/socketio-server, only implements the WebSocket transport and documents the 2.x client.
The first idea would be to update phpsocket.io itself. The problem is the incompatibility: switching the protocol would break everyone using the package today, because the old clients would stop connecting. Migrating means changing the client and the server together, and that has to be each project's decision, not a composer update.
There's also the PHP version. phpsocket.io runs on Workerman 4 and accepts PHP 7.4, and the people using it today may be on older versions. Workerman 5, the current version, requires PHP 8.1, so moving phpsocket.io to it would force everyone to upgrade PHP along with it. A new package could start from a current base without breaking anyone: PHP 8.1 or later, Workerman 5, types everywhere and PHPStan at the maximum level. phpsocket.io keeps serving the 1.x and 2.x clients, and socket.io-server the v3 and v4 ones.
To make migrating easier, the server's API follows phpsocket.io's shape, and the repository has a migration guide covering what changes in the code and on the client.
phpsocket.io's README already points to socket.io-server for anyone who needs the v3 and v4 clients.
What it does
A complete server fits in a few lines:
<?php
use Marcolin\SocketIO\Socket;
use Marcolin\SocketIO\SocketIO;
use Workerman\Worker;
require __DIR__ . '/vendor/autoload.php';
$io = new SocketIO(3000, ['cors' => ['origin' => ['https://example.com']]]);
$io->on('connection', function (Socket $socket) use ($io): void {
$socket->join('lobby');
$socket->emit('hello', 'world');
$socket->on('chat', function (string $message, ?Closure $ack = null) use ($io): void {
$io->to('lobby')->emit('chat', $message);
if ($ack !== null) {
$ack('delivered');
}
});
});
Worker::runAll();
And on the client, the official socket.io-client:
import { io } from "socket.io-client";
const socket = io("http://localhost:3000");
socket.on("hello", (word) => console.log(word));
socket.emit("chat", "hi", (status) => console.log(status)); // "delivered"
What's already implemented:
- Transports: HTTP long-polling and WebSocket on the same port, with the upgrade from one to the other (no WebTransport yet);
- Protocol features: namespaces (separate channels on the same server, such as
/chatand/admin), middlewares, rooms, acknowledgements (broadcasts too, with a timeout), binary data and catch-all listeners (which receive any event); - Connection state recovery: a client that lost its connection comes back with the same socket, the same rooms and the events it missed;
- Several processes and machines: an event sent in one process reaches the clients connected to the others, through workerman/channel (Workerman's own message server), Redis pub/sub or Redis Streams;
- The rest: CORS with cookies, TLS, compression, a debug log and the official Admin UI (a web panel to watch sockets, rooms and events live).
Where it makes the most sense: when the team and the application are PHP. With the Emitter, a regular PHP-FPM request sends events to the connected clients, through Redis, without running a Node.js service just for that. If the application is already Node, the official server is still the natural choice.
To know whether the server speaks the protocol correctly, it runs the official compliance suites for Engine.IO (25 of 25 tests) and Socket.IO (32 of 32) on every pull request, plus integration tests with the official client, on PHP 8.1 to 8.5.
What you can build
The repository's examples show how the package works, not the limit of what you can do with it. Some of them:
- Chat and private messages, with a typing indicator and messages that reach users who dropped and came back (chat, private-messaging);
- Notifications triggered by the PHP application itself (emitter);
- Live dashboards, with the server pushing new numbers to whoever is watching each one (dashboard);
- Multiplayer games: a Pong with a match queue and a space arena with bots, with the game loop running on the server at 30 frames per second (pong, arena).
There are 14 examples in all, and each one runs with a single command. Beyond them, the package fits anything that needs real-time updates, such as order and delivery tracking, auctions, support queues, collaborative editing and monitoring alerts.
In production
The server is a long-lived PHP process, so in production it has to stay up at all times and come back on its own if it dies. For that I use Supervisor, running the server in the foreground (start, without -d) and letting it take control:
[program:socketio]
command=php -d memory_limit=512M /var/www/app/server.php start
directory=/var/www/app
user=www-data
autostart=true
autorestart=true
stopsignal=INT
stopasgroup=true
killasgroup=true
redirect_stderr=true
stdout_logfile=/var/log/socketio.log
With that, supervisorctl start socketio, stop, restart and status control the process, it starts with the machine and restarts if it dies. Two things to watch: the open files limit has to be higher than the number of connections (in Supervisor, minfds in the [supervisord] section), and the OPcache and JIT settings from the performance section apply here too.
Performance against the official server
I ran the same load test on socket.io-server and on the official server (socket.io 4.8.4 on Node.js 24): one process each, the same handlers and the same machine (a MacBook Pro M4 Pro, all in Docker), with the official socket.io-client over WebSocket and the event extension on PHP, which gives Workerman an event loop that handles thousands of connections (without it, it uses select(), limited to about a thousand). Each number is the median of three runs, all in the same session.
It's a simple benchmark, with a margin of error: the numbers vary by up to 10% between sessions, and up to 15% within one session at 1,000 clients. The server and the clients run together on a single machine, so the numbers are meant to compare the servers with each other, not as the capacity of a production server. Measuring a system in production is hard: the network, the hardware, the size of the messages and the application's own code all change the result. These tests are an estimate, not a promise.
Each measurement has three parts:
- Memory: the process's total RSS with every client connected;
- Acknowledgements: each client sends 20 messages in sequence, waiting for each answer, all clients at once;
- Broadcasts: 50 events of 100 bytes to every client at once.
On the PHP side, I measured two setups: PHP 8.1 out of the box, and PHP 8.5 with OPcache and the JIT on. I explain why right after the charts.
On memory, PHP stays below at every size. The biggest gap is at the start: the PHP process begins at about 13 MB, Node at 64 MB. At 10,000 clients the gap shrinks to 5%. Each connection costs about 25 KB, and growth is linear. The JIT costs 8 to 13 MB, once, not per connection.
On acknowledgements, at 1,000 clients all three are within the normal run-to-run variation. From 5,000 on, PHP 8.1 falls behind: Node answers 21% to 29% more per second. With the JIT, PHP ties at 5,000 clients and is 7% behind at 10,000.
Broadcasts tell the same story. Without the JIT, Node delivers 1.2 to 1.4 times as many per second. With it, PHP ties at 1,000 and 10,000 clients and is 8% behind at 5,000.
Throughput doesn't say how long a message takes to arrive. For that, I measured the latency of a broadcast to a room of a thousand clients, with 10,000 connected: 100 messages, one every 50 ms, timed from the request to the arrival at each member. The clients are spread over 10 containers, a thousand in each, so that no client process becomes the bottleneck. The p99 is the time by which 99% of the deliveries have arrived.
The three are practically the same, around 7 ms at p50 and 14 ms at p99, a difference below the run-to-run variation. At this load, none of the servers is the bottleneck: the server and the clients share the same machine and Docker's network, and that environment sets the time. Telling one server from the other would take running the clients on other machines.
PHP leaves OPcache off on the command line (opcache.enable_cli=0), and a Workerman server is a CLI process. So, without any configuration, it runs interpreted, while V8, Node's engine, JIT-compiles the hottest code without any configuration. For a fair comparison, the JIT has to be on:
; PHP 8.1 to 8.4 also need zend_extension=opcache, PHP 8.5 builds it in
opcache.enable_cli=1
opcache.jit=tracing
opcache.jit_buffer_size=128M
Comparing PHP 8.1 without the JIT to 8.5 with it changes two things at once, so I also measured the other two combinations. The gain comes from the JIT, not the version: with the JIT, PHP 8.1 answers 94,000 acknowledgements per second with 5,000 clients and 85,000 with 10,000, nearly the same as 8.5 (96,000 and 87,000). And 8.5 without the JIT stays level with 8.1 on acknowledgements and delivers 4% to 14% more broadcasts.
The profiler shows where the JIT acts. The largest cost of a delivery is the write system call on the socket (about 1.5 µs), Workerman adds about 0.25 µs and the package's code about 0.6 µs. The JIT only speeds up that last part. That's why a single event to 10,000 clients, which is basically one write per client, barely changes: 133,000 deliveries per second without the JIT, 138,000 with it, and 154,000 on Node.
The full methodology and the scripts to run it on your machine are in docs/performance.md.
Continuous load test without leaking memory
A WebSocket server stays up for days, so memory has to stay flat while clients come and go. The soak test simulates that: thousands of clients connecting and leaving, over long-polling, WebSocket or the upgrade, with binary data and rooms, and 30% of them dropping their transport to test recovery. Every 200 ms a numbered broadcast goes out, and every client checks whether it lost, repeated or got anything out of order.
The result of 20 minutes with 2,000 clients (about 1,850 connected at a time):
| Connections opened | 81,615 (about 68 per second) |
| Transports dropped | 17,615, with 17,560 recovered and none failed (the rest ended first) |
| Numbered messages received | 11,012,036, none lost, repeated or out of order |
| Memory (heap) during the test | 53.1 to 54.8 MB, flat from start to end |
| Memory after the clients left | 7.8 MB |
The most useful part was what it found before it passed: up to version 0.5.1, every closed connection left about 7 KB behind, because the map from sessions to clients was never cleared. Memory went from 66 MB to 812 MB in 17 minutes, with the CPU at 100%. No unit test caught it. The fix shipped in 0.5.2.
Building it with AI
I built the package together with Claude (Opus 5.5). What made that workable was the problem having a clear reference: the protocol is documented, the official server is there to compare against and the compliance suites say objectively whether the implementation is right. Every step had a definition of done that didn't depend on anyone's opinion, not mine and not the AI's.
What I take from the experience:
- Real tests are worth more than review. The code passed every test and had a memory leak. Only the soak test found it;
- Intermittent bugs take patience. One test in the official suite failed once every 60 runs. The cause: Workerman's
select()reads ready sockets in descriptor order, not arrival order, so a polling request sent right after the upgrade was sometimes read before it. Finding that took more work than many whole features; - Measure before optimizing. The package's optimizations came from profiling, not guesses. Grouping each connection's writes doubled broadcast deliveries, but grouping the first write too made a single event to many clients 30% slower and was dropped.
Current state and next steps
The package is on Packagist, at version 0.x, and works on PHP 8.1 to 8.5, and also on the event loop of Swoole, the asynchronous programming extension for PHP, for those who already use it. The next step is seeing it run in real applications. I've also opened a pull request to add the package, along with phpsocket.io, to the list of server implementations on the Socket.IO website, which is still waiting for review.
Conclusion
With socket.io-server, a PHP application no longer needs a Node.js service on the side just to use the current version of Socket.IO. Everything can stay on the same stack, with the official client and the features that came after 2.x.
Two lessons apply even if you never use the package. If you run long-lived PHP on the command line, check whether OPcache and the JIT are on, because by default they aren't. And sustained load testing catches what unit tests don't.
To try it, the migration guide and the repository's examples are a good place to start.
FAQ
Can I use Socket.IO v4 with PHP?
Yes. socket.io-server is a Socket.IO v4 server in PHP, built on Workerman, that works with the official socket.io-client v3 and v4. It runs as a long-lived PHP process, separate from PHP-FPM.
Does phpsocket.io support socket.io-client v3 and v4?
No. phpsocket.io implements Engine.IO v3 and only works with the 1.x and 2.x clients. For v3 and v4, phpsocket.io's own README points to socket.io-server, which has a migration guide.