Socket.IO v4 em PHP: servidor novo e benchmark com Node.js

Marcos Marcolin • 16 de novembro de 2026 • 15 min de leitura

PHP Open Source

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?

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:

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:

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:

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:

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.

Links

Compartilhar: