Desde 2021 eu uso o phpsocket.io em produção. Ele entrou pra substituir um servidor legado em Node.js. Comecei como usuário, passei a contribuir com o projeto e, com o tempo, fui convidado a ser um dos mantenedores. É o pacote de Socket.IO mais usado no ecossistema PHP, mas ele tem uma limitação que pesa cada vez mais: só fala o protocolo antigo, então funciona apenas com o socket.io-client 1.x e 2.x. Ele também continua no Workerman 4, porque o Workerman 5 exige PHP 8.1 e o pacote ainda atende quem está no PHP 7.4.
Pra resolver isso, criei o socket.io-server, um servidor Socket.IO v4 para PHP, feito sobre o Workerman, um framework PHP pra servidores de rede assíncronos, que roda como um processo próprio, fora do PHP-FPM. Ele funciona com o socket.io-client oficial v3 e v4, segue uma API parecida com a do phpsocket.io e, com OPcache e JIT ligados, chega perto do servidor oficial em Node.js gastando menos memória.
O pacote está na versão 0.x e já pode ser usado. Se você precisa de Socket.IO v4 em PHP, ou quer sair do client 2.x, testa e me conta como foi: feedback, issues e pull requests são muito bem-vindos.
Sumário
- Socket.IO ou WebSocket: qual a diferença?
- Por que o phpsocket.io não funciona com o socket.io-client v3 e v4
- Por que um pacote novo
- O que ele faz
- Performance contra o servidor oficial
- Horas de carga sem vazar memória
- Como foi construir com IA
- Estado atual e próximos passos
- Conclusão
- Perguntas frequentes
Socket.IO ou WebSocket: qual a diferença?
O WebSocket é um protocolo padrão da web que mantém uma conexão aberta entre client e servidor, pra que os dois mandem mensagens a qualquer momento, sem o client ter que ficar perguntando. Mas ele entrega só isso: mensagens soltas, de texto ou binárias. Reconexão, saber qual resposta é de qual pergunta, mandar pra um grupo de usuários, tudo fica por sua conta.
O Socket.IO nasceu em 2010 como uma biblioteca pra Node.js, e o servidor oficial continua sendo em Node. O protocolo dele é documentado, o que permite implementar servidores e clients em outras linguagens, como Java, Python e Rust.
Ele não é uma alternativa ao WebSocket: usa o WebSocket como transporte e acrescenta, por cima, o que falta. São eventos com nome (emit e on), respostas por callback (os acknowledgements), rooms pra mandar mensagem pra grupos, reconexão automática e fallback pra HTTP long-polling (requisições HTTP que ficam abertas até ter algo pra responder) quando um proxy ou firewall bloqueia o WebSocket. Como ele tem protocolo próprio, um client Socket.IO não conversa com um servidor WebSocket puro, nem o contrário: o servidor também precisa falar Socket.IO, e na versão certa.
Por que o phpsocket.io não funciona com o socket.io-client v3 e v4
O Socket.IO tem duas camadas. Por baixo está o Engine.IO, que cuida da conexão: abre por HTTP long-polling, sobe pra WebSocket quando dá e mantém o heartbeat. Por cima está o Socket.IO, com eventos, namespaces, rooms e acknowledgements.
Na versão 3.0 do Socket.IO, lançada em 2020, as duas camadas mudaram de protocolo: o Engine.IO foi pra v4 e o Socket.IO pra v5. E a mudança é incompatível nos dois sentidos. Por padrão, um client 2.x não conecta num servidor v4 (o servidor oficial em Node tem a opção allowEIO3 pra aceitar os clients antigos durante uma migração), e um client v3 ou v4 não conecta num servidor antigo.
O phpsocket.io implementa o protocolo antigo (Engine.IO v3). Na prática, quem usa PHP no servidor fica preso à linha 2.x do client JavaScript, que parou de receber recursos novos em 2020 (a última versão, a 2.5.0, é de 2022), sem o que veio depois, como a recuperação de estado da conexão.
Por que um pacote novo
Hoje não existe servidor PHP pro Socket.IO v4 na lista oficial de implementações do site. O outro pacote conhecido, o hyperf/socketio-server, implementa só o transporte WebSocket e documenta o client 2.x.
A primeira ideia seria atualizar o próprio phpsocket.io. O problema é a incompatibilidade: trocar o protocolo quebraria todo mundo que usa o pacote hoje, porque os clients antigos deixariam de conectar. Migrar exige trocar client e servidor juntos, e isso tem que ser decisão de cada projeto, não um composer update.
Tem também a versão do PHP. O phpsocket.io roda no Workerman 4 e aceita PHP 7.4, e quem usa ele hoje pode estar em versões antigas. O Workerman 5, a versão atual, exige PHP 8.1, então levar o phpsocket.io pra ele obrigaria todo mundo a atualizar o PHP junto. Num pacote novo, dava pra partir de uma base atual sem quebrar ninguém: PHP 8.1 ou superior, Workerman 5, tipos em tudo e PHPStan no nível máximo. O phpsocket.io segue atendendo os clients 1.x e 2.x, e o socket.io-server os v3 e v4.
Pra facilitar a migração, a API do servidor segue o formato da do phpsocket.io, e o repositório tem um guia de migração com o que muda no código e no client.
O README do phpsocket.io já indica o socket.io-server pra quem precisa dos clients v3 e v4.
O que ele faz
Um servidor completo cabe em poucas linhas:
<?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();
E no client, o socket.io-client oficial:
import { io } from "socket.io-client";
const socket = io("http://localhost:3000");
socket.on("hello", (word) => console.log(word));
socket.emit("chat", "oi", (status) => console.log(status)); // "delivered"
O que já está implementado:
- Transportes: HTTP long-polling e WebSocket na mesma porta, com o upgrade de um pro outro;
- Recursos do protocolo: namespaces (canais separados no mesmo servidor, como
/chate/admin), middlewares, rooms, acknowledgements (inclusive em broadcast, com timeout), dados binários e listeners catch-all (que recebem qualquer evento); - Recuperação de estado da conexão: um client que perdeu a conexão volta com o mesmo socket, as mesmas rooms e os eventos que perdeu;
- Vários processos e máquinas: um evento enviado num processo chega aos clients conectados nos outros, via workerman/channel (um servidor de mensagens do próprio Workerman), Redis pub/sub ou Redis Streams;
- O resto: CORS com cookies, TLS, compressão, log de debug e o Admin UI oficial (um painel web pra ver sockets, rooms e eventos ao vivo).
Onde ele faz mais sentido: quando o time e a aplicação são PHP. Com o Emitter, uma requisição comum no PHP-FPM manda eventos pros clients conectados, via Redis, sem precisar manter um serviço em Node.js só pra isso. Se a aplicação já é Node, o servidor oficial continua sendo a escolha natural.
Pra saber se o servidor fala o protocolo do jeito certo, ele roda as suítes de conformidade oficiais do Engine.IO (25 de 25 testes) e do Socket.IO (32 de 32) em todo pull request, além de testes de integração com o client oficial, do PHP 8.1 ao 8.5.
O que dá pra construir
Os exemplos do repositório mostram como o pacote funciona, não o limite do que dá pra fazer com ele. Alguns deles:
- Chat e mensagens privadas, com indicador de digitação e mensagens que chegam pra quem caiu e voltou (chat, private-messaging);
- Notificações disparadas pela própria aplicação PHP (emitter);
- Dashboards ao vivo, com o servidor empurrando números novos pra quem está olhando cada painel (dashboard);
- Jogos multiplayer: um Pong com fila de partidas e uma arena espacial com bots, com o loop do jogo rodando no servidor a 30 quadros por segundo (pong, arena).
São 14 exemplos ao todo, e cada um roda com um comando. Fora deles, o pacote serve pra qualquer coisa que precise de atualização em tempo real, como acompanhamento de pedidos e entregas, leilões, filas de atendimento, edição colaborativa e alertas de monitoramento.
Em produção
O servidor é um processo PHP de longa duração, então em produção ele precisa ficar sempre de pé e voltar sozinho se cair. Pra isso eu uso o Supervisor, rodando o servidor em primeiro plano (start, sem o -d) e deixando o controle com ele:
[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
Com isso, supervisorctl start socketio, stop, restart e status controlam o processo, ele sobe junto com a máquina e é reiniciado se cair. Dois cuidados: o limite de arquivos abertos precisa ser maior que o número de conexões (no Supervisor, minfds na seção [supervisord]), e as configurações de OPcache e JIT da seção de performance valem aqui também.
Performance contra o servidor oficial
Rodei o mesmo teste de carga no socket.io-server e no servidor oficial (socket.io 4.8.4 no Node.js 24): um processo cada, mesmos handlers e mesma máquina (um MacBook Pro M4 Pro, tudo em Docker), com o socket.io-client oficial via WebSocket e a extensão event no PHP, que dá ao Workerman um event loop capaz de milhares de conexões (sem ela, ele usa o select(), limitado a cerca de mil). Cada número é a mediana de três execuções, todas na mesma sessão.
É um benchmark simples, com margem de erro: os números variam até 10% entre sessões, e até 15% dentro da mesma sessão com mil clientes. Servidor e clients rodam juntos numa única máquina, então os números servem pra comparar os servidores entre si, não como a capacidade de um servidor em produção.
Cada medição tem três partes:
- Memória: o RSS total do processo com todos os clients conectados;
- Acknowledgements: cada client envia 20 mensagens em sequência, esperando a resposta, todos ao mesmo tempo;
- Broadcasts: 50 eventos de 100 bytes pra todos os clients de uma vez.
Do lado do PHP, medi duas configurações: o PHP 8.1 como vem, e o PHP 8.5 com OPcache e JIT ligados. Explico o motivo logo depois dos gráficos.
Na memória, o PHP fica abaixo em todos os tamanhos. A maior diferença está no início: o processo PHP começa com cerca de 13 MB, e o Node com 64 MB. Com 10 mil clientes a diferença cai pra 5%. Cada conexão custa cerca de 25 KB, e o crescimento é linear. O JIT custa de 8 a 13 MB, uma vez só, não por conexão.
Nos acknowledgements, com mil clientes os três ficam dentro da variação normal entre execuções. A partir de 5 mil, o PHP 8.1 fica pra trás: o Node responde de 21% a 29% mais por segundo. Com JIT, o PHP empata com 5 mil clientes e fica 7% abaixo com 10 mil.
Nos broadcasts acontece o mesmo. Sem JIT, o Node entrega de 1,2 a 1,4 vez mais por segundo. Com JIT, o PHP empata com mil e 10 mil clientes e fica 8% abaixo com 5 mil.
O PHP deixa o OPcache desligado na linha de comando (opcache.enable_cli=0), e um servidor Workerman é um processo CLI. Ou seja, sem configurar nada, ele roda interpretado, enquanto o V8, motor do Node, compila com JIT o código mais executado sem precisar configurar nada. Pra uma comparação justa, o JIT precisa estar ligado:
; do PHP 8.1 ao 8.4 também precisa de zend_extension=opcache, o 8.5 já vem com ele
opcache.enable_cli=1
opcache.jit=tracing
opcache.jit_buffer_size=128M
O profiler mostra onde o JIT age. O maior custo de uma entrega é a chamada de sistema de escrita no socket (cerca de 1,5 µs), o Workerman adiciona uns 0,25 µs e o código do pacote cerca de 0,6 µs. O JIT só acelera essa última parte. Por isso um único evento pra 10 mil clientes, que é basicamente uma escrita por client, quase não muda: 133 mil entregas por segundo sem JIT, 138 mil com, e 154 mil no Node.
A metodologia completa e os scripts pra rodar na sua máquina estão em docs/performance.md.
Horas de carga sem vazar memória
Um servidor de WebSocket fica dias no ar, então a memória precisa ficar estável enquanto os clients entram e saem. O soak test simula isso: milhares de clients conectando e saindo, por long-polling, WebSocket ou upgrade, com dados binários e rooms, e 30% deles derrubando o transporte pra testar a recuperação. A cada 200 ms sai um broadcast numerado, e cada client confere se perdeu, repetiu ou recebeu algo fora de ordem.
O resultado de 20 minutos com 2 mil clientes (cerca de 1.850 conectados ao mesmo tempo):
| Conexões abertas | 81.615 (cerca de 68 por segundo) |
| Transportes derrubados | 17.615, com 17.560 recuperados e nenhuma falha (o resto encerrou antes) |
| Mensagens numeradas recebidas | 11.012.036, nenhuma perdida, repetida ou fora de ordem |
| Memória (heap) durante o teste | de 53,1 a 54,8 MB, estável do início ao fim |
| Memória depois que os clients saíram | 7,8 MB |
O mais útil foi o que ele encontrou antes de passar: até a versão 0.5.1, cada conexão encerrada deixava uns 7 KB pra trás, porque o mapa de sessões pra clients nunca era limpo. A memória ia de 66 MB a 812 MB em 17 minutos, com a CPU em 100%. Nenhum teste unitário pegou isso. A correção saiu na 0.5.2.
Como foi construir com IA
Construí o pacote junto com o Claude (Opus 5.5). O que tornou isso viável foi o problema ter uma referência clara: o protocolo é documentado, o servidor oficial serve de comparação e as suítes de conformidade dizem objetivamente se a implementação está certa. Cada etapa tinha um critério de pronto que não dependia da opinião de ninguém, nem minha nem da IA.
O que eu levo dessa experiência:
- Testes de verdade valem mais que revisão. O código passava em todos os testes e tinha um vazamento de memória. Só o soak test encontrou;
- Bugs intermitentes exigem paciência. Um teste da suíte oficial falhava uma vez a cada 60 execuções. A causa: o
select()do Workerman lê os sockets prontos na ordem do descritor, não na ordem de chegada, então uma requisição de polling enviada logo depois do upgrade às vezes era lida antes dele. Achar isso deu mais trabalho que muita feature inteira; - Medir antes de otimizar. As otimizações do pacote vieram de profiling, não de palpite. Agrupar as escritas de cada conexão dobrou as entregas de broadcast, mas agrupar inclusive a primeira escrita deixou um único evento pra muitos clients 30% mais lento e foi descartado.
Estado atual e próximos passos
O pacote está no Packagist, na versão 0.x, e funciona do PHP 8.1 ao 8.5, e também com o event loop do Swoole, a extensão de programação assíncrona pra PHP, pra quem já usa. O próximo passo é ver ele rodando em aplicações reais. Também abri um pull request pedindo pra incluir o pacote, junto com o phpsocket.io, na lista de implementações de servidor do site do Socket.IO, que ainda aguarda revisão.
Conclusão
Com o socket.io-server, uma aplicação PHP não precisa mais de um serviço em Node.js do lado só pra usar a versão atual do Socket.IO. Dá pra manter tudo na mesma stack, com o client oficial e os recursos que vieram depois da 2.x.
Dois aprendizados valem mesmo pra quem nunca vai usar o pacote. Se você roda PHP de longa duração na linha de comando, confira se o OPcache e o JIT estão ligados, porque por padrão não estão. E teste de carga contínua pega o que teste unitário não pega.
Pra testar, o guia de migração e os exemplos do repositório são um bom ponto de partida.
Perguntas frequentes
Dá pra usar Socket.IO v4 com PHP?
Sim. O socket.io-server é um servidor Socket.IO v4 em PHP, feito sobre o Workerman, que funciona com o socket.io-client oficial v3 e v4. Ele roda como um processo PHP de longa duração, separado do PHP-FPM.
O phpsocket.io suporta o socket.io-client v3 e v4?
Não. O phpsocket.io implementa o Engine.IO v3 e só funciona com os clients 1.x e 2.x. Pra v3 e v4, o próprio README do phpsocket.io indica o socket.io-server, que tem um guia de migração.