Configurando e Executando Aplicativos Workerman no ServBay

Visão Geral

Este documento tem como objetivo orientar usuários do ServBay sobre como configurar rapidamente, em um ambiente de desenvolvimento local no macOS, aplicações de rede assíncronas de alto desempenho baseadas em Workerman, utilizando o ambiente PHP integrado do ServBay e o Composer. Workerman é uma poderosa biblioteca PHP adequada para construir diversos serviços de rede que exigem processamento de alta concorrência, como servidores Web, servidores de comunicação em tempo real, servidores de jogos, entre outros. O ServBay oferece uma plataforma de desenvolvimento pronta para uso, simplificando bastante o processo de configuração do ambiente para o Workerman.

O que é o Workerman?

Workerman é um framework open-source, totalmente escrito em PHP, que oferece comunicação de rede assíncrona de alto desempenho. Baseado no mecanismo de EventLoop, ele implementa I/O assíncrono e não bloqueante, sendo capaz de lidar com um grande número de conexões simultâneas. Diferente do modelo tradicional de desenvolvimento Web em PHP (como Apache/Nginx + PHP-FPM), aplicações Workerman geralmente rodam em memória, escutando portas específicas e processando conexões e dados diretamente. Isso elimina a sobrecarga de criar e destruir processos por requisição, aumentando significativamente o desempenho e a vazão.

Com Workerman, os desenvolvedores podem facilmente construir:

• Servidores HTTP de alto desempenho, podendo inclusive substituir Apache/Nginx para processar requisições simples estáticas ou dinâmicas.
• Servidores WebSocket em tempo real, para construir chats, push de dados em tempo real, etc.
• Servidores TCP/UDP para protocolos personalizados.
• Ferramentas de linha de comando, tarefas agendadas, microsserviços e muito mais.

Principais Características e Vantagens do Workerman

• Alto desempenho: Construído sobre evento assíncrono e I/O não bloqueante, capaz de gerenciar milhares de conexões concorrentes com máxima eficiência.
• Suporte a múltiplos protocolos: Suporte nativo para HTTP, WebSocket, TCP, UDP e outros protocolos, além de interfaces flexíveis para implementação de protocolos personalizados.
• Fácil de usar: API simples e direta, reduzindo a complexidade da programação de redes assíncronas, permitindo que desenvolvedores PHP iniciem rapidamente.
• Escalabilidade flexível: Suporte a modelo multiprocessado, aproveitando múltiplos núcleos da CPU para escalabilidade horizontal e balanceamento de carga. Integração fácil com pacotes Composer e bibliotecas PHP existentes.
• Integração com o ecossistema PHP: Sendo uma biblioteca PHP, trabalha harmoniosamente com o ecossistema, permitindo gerenciamento de dependências via Composer.
• Modo daemon: Suporte para execução em segundo plano como daemon, ideal para ambientes de produção e garantindo alta disponibilidade do serviço.

Workerman abre as portas para desenvolvedores PHP criarem aplicações de rede de alta performance, em tempo real e com grande volume de conexões simultâneas.

Montando o Ambiente de Desenvolvimento Workerman no ServBay

ServBay é uma ferramenta de ambiente local desenvolvida especialmente para web developers, integrando os principais runtimes de linguagens como PHP, Node.js, Python, Go, Java e bancos de dados/servidores populares: Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached, entre outros. Seu maior diferencial é ser “pronto para uso”, especialmente pela configuração já preparada do Composer, o que facilita muito a instalação e execução de projetos Workerman no ServBay.

Este guia mostrará, através de exemplos práticos, como configurar e rodar rapidamente aplicações Workerman no ServBay, incluindo um servidor HTTP simples, um servidor WebSocket e um servidor TCP.

TIP

Para facilitar o gerenciamento e manter a padronização, o ServBay recomenda salvar todos os projetos de sites locais na pasta /Applications/ServBay/www. Todos os exemplos de caminhos neste documento usarão esse diretório como base.

Pré-requisitos

Antes de começar, certifique-se de que:

1. ServBay está instalado e em funcionamento: Baixe e instale a versão mais recente do ServBay no site oficial.
2. PHP está habilitado no ServBay: No painel do ServBay, garanta que a versão do PHP desejada está ativada. O Workerman exige PHP 5.4 ou superior; recomenda-se PHP 7.x ou 8.x para melhor desempenho.
3. Conhecimento básico em PHP e comandos de terminal: É importante saber o básico de PHP e como utilizar ferramentas via linha de comando no terminal.

Instalando o Workerman

1. Garanta que o Composer está disponível

O ServBay já vem com o Composer integrado — não é necessário instalar separadamente. Certifique-se que o ambiente do ServBay está ativo e o PHP que você irá usar está habilitado. O próprio ServBay cuida das configurações do Composer referente à versão do PHP usada. Você pode usar o terminal integrado do ServBay ou um terminal externo (caso o ServBay adicione o PHP e Composer ao PATH do sistema) para acessar o ambiente PHP do ServBay.

Abra um terminal e execute o comando abaixo para verificar se o Composer está disponível:

composer -v

Se estiver corretamente instalado e configurado no ambiente PHP do ServBay, você verá as informações da versão do Composer. Se o comando não for encontrado, verifique se o ServBay está rodando e se o PHP está ativado.

2. Crie o diretório do projeto

Navegue até o diretório raiz recomendado pelo ServBay e crie uma nova pasta para o projeto, entrando nela em seguida:

cd /Applications/ServBay/www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

Neste exemplo, criamos a pasta servbay-workerman-demo para armazenar os arquivos do projeto Workerman.

3. Instale o Workerman via Composer

Dentro do diretório do projeto (/Applications/ServBay/www/servbay-workerman-demo), instale o Workerman usando o Composer. Esse é o método recomendado, pois o Composer cuida automaticamente das dependências:

composer require workerman/workerman

O Composer fará o download do Workerman e suas dependências para o diretório vendor.

Escrevendo o Código do Servidor HTTP Workerman

Um dos usos mais populares do Workerman é como servidor HTTP, ideal para construir web apps de alta performance ou APIs.

No diretório do projeto, crie um arquivo chamado http_server.php (ou outro nome de sua preferência, como server.php) e adicione o código PHP abaixo:

<?php
// Inclua o autoloader do Composer para usar as classes do Workerman
require __DIR__ . '/vendor/autoload.php';

// Importe a classe Worker do Workerman
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// Crie uma instância do Worker especificando o protocolo e endereço de escuta
// 'http://0.0.0.0:8080' indica um servidor HTTP escutando todas as interfaces na porta 8080
// 0.0.0.0 permite acesso tanto do próprio computador quanto de outros dispositivos da rede local; 8080 é a porta monitorada
$http_worker = new Worker('http://0.0.0.0:8080');

// Defina o número de processos do Worker
// Neste exemplo, 4 processos PHP independentes para processar requisições, podendo ajustar conforme o número de núcleos
$http_worker->count = 4;

// Defina a lógica para processar mensagens dos clientes (requisições HTTP)
// $connection é o objeto da conexão atual, usado para responder ao cliente
// $request contém detalhes da requisição (URL, Headers, Body, etc)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Envie uma resposta HTTP como string simples ao cliente
    // O protocolo HTTP do Workerman cuidará dos detalhes do cabeçalho automaticamente
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// Execute todas as instâncias Worker
// Este é o loop principal do Workerman: ativa os processos, monitora portas e lida com eventos
Worker::runAll();

Explicação do código:

• require __DIR__ . '/vendor/autoload.php';: Carrega o autoloader gerado pelo Composer, permitindo o uso das classes do Workerman (Worker, Request, Response etc).
• use Workerman\...;: Importa as classes necessárias.
• new Worker('http://0.0.0.0:8080'): Cria uma instância do Workerman. O argumento especifica o protocolo (http) e endereço (0.0.0.0:8080).
• $http_worker->count = 4;: Define o número de processos que o Workerman usará. Ao aumentar, aproveita-se melhor CPUs multicore para concorrência.
• $http_worker->onMessage = function(...) { ... };: Callback executado ao receber uma requisição HTTP completa. $connection serve para enviar os dados ao cliente e $request contém os dados recebidos. A classe Response constrói uma resposta HTTP padrão.
• Worker::runAll();: Inicializa o loop de eventos do Workerman, começando a monitorar e processar conexões.

Executando o Servidor HTTP Workerman

Dentro do diretório do projeto (/Applications/ServBay/www/servbay-workerman-demo), abra o terminal e execute o comando:

php http_server.php start

Sobre os modos de execução:

• Modo Foreground (primeiro plano): Executando php http_server.php start, o Workerman roda no primeiro plano, mostrando logs e informações no terminal. Use Ctrl+C para parar o servidor. Ideal para desenvolvimento e testes.
• Modo Daemon (background): Para produção, é recomendado rodar como daemon com a opção -d:

  php http_server.php start -d

  O Workerman rodará em segundo plano e registrará logs em arquivos (por padrão, no diretório do Workerman ou local definido).

Gestão de processos:

O Workerman oferece comandos práticos para gerenciar processos:

• Iniciar: php http_server.php start (foregroud) ou php http_server.php start -d (daemon)
• Parar: php http_server.php stop (encerra graciosamente após terminar as solicitações abertas)
• Reiniciar: php http_server.php restart (para e inicia novamente)
• Reload suave: php http_server.php reload (útil após atualizar o código, reinicia filhos um a um sem interromper o serviço; atenção especial a hooks de ciclo de vida como onWorkerStart)
• Ver status: php http_server.php status (exibe status dos processos Workerman, uso de memória, conexões ativas, etc)

Ao iniciar o servidor, acesse no navegador: http://localhost:8080 ou http://127.0.0.1:8080. Você deverá ver a mensagem: Hello ServBay Workerman HTTP Server!.

Criando um Servidor WebSocket com Workerman

O protocolo WebSocket permite comunicação bidirecional persistente entre cliente e servidor, ideal para aplicações em tempo real como chats online, cotações em tempo real, jogos, etc. O Workerman oferece suporte eficiente a WebSocket.

1. Crie o código do servidor WebSocket

   No diretório do projeto, crie o arquivo websocket_server.php e adicione o seguinte código:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crie uma instância do servidor WebSocket escutando na porta 8081
   // 'websocket://0.0.0.0:8081' cria um servidor WebSocket
   // O Workerman cuida do handshake do WebSocket automaticamente
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Inicie 4 processos para lidar com as conexões
   $ws_worker->count = 4;
   
   // Lógica ao estabelecer uma nova conexão
   // Disparado quando um novo cliente se conecta
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nova conexão WebSocket de " . $connection->getRemoteIp() . "\n";
   };
   
   // Lógica para recebimento de mensagens
   // Disparado ao receber mensagens WebSocket do cliente
   // $data contém o conteúdo já decodificado da mensagem do cliente
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Mensagem recebida: " . $data . "\n";
       // Reenvia a mensagem recebida de volta ao cliente
       // $connection->send() codifica automaticamente em WebSocket frame
       $connection->send('ServBay Workerman recebeu: ' . $data);
   };
   
   // Lógica ao fechar conexão
   // Disparado quando o cliente desconecta
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Conexão WebSocket encerrada\n";
   };
   
   // Lógica para erros (opcional)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Erro: $code - $msg\n";
   };
   
   
   // Rode todas as instâncias Worker
   Worker::runAll();

2. Execute o servidor WebSocket

   No diretório do projeto, rode:

   php websocket_server.php start

   Você também pode usar o modo daemon com -d para rodar em background. Após iniciar, utilize um cliente WebSocket para conectar a ws://localhost:8081.

   Por exemplo, você pode testar usando o console do navegador com JavaScript:

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("Conexão WebSocket aberta");
     ws.send("Olá do navegador!"); // Envia mensagem
   };
   
   ws.onmessage = function(event) {
     console.log("Mensagem do servidor:", event.data); // Recebe mensagens
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Conexão WebSocket fechada corretamente, code=" + event.code + " motivo=" + event.reason);
     } else {
       console.error("Conexão WebSocket caiu");
     }
   };
   
   ws.onerror = function(error) {
     console.error("Erro WebSocket:", error);
   };
   
   // Para fechar (opcional)
   // ws.close();

   Após conectar, verá informações no terminal sobre as conexões; ao enviar mensagens, receberá de volta do servidor as respostas.

Criando um Servidor TCP com Workerman

O Workerman também pode ser usado para construir servidores TCP genéricos, processando qualquer tipo de aplicação baseada em TCP. Excelente para backends de jogos, IoT, comunicação personalizada, etc.

1. Código do servidor TCP

   No diretório do projeto, crie tcp_server.php com o seguinte código:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Cria servidor TCP na porta 8082
   // 'tcp://0.0.0.0:8082' cria servidor TCP
   // Workerman usa protocolo Text (finalização por '\n') por padrão, mas pode-se mudar
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Inicie 4 processos para lidar com as conexões
   $tcp_worker->count = 4;
   
   // Nova conexão estabelecida
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nova conexão TCP de " . $connection->getRemoteIp() . "\n";
       // Envia mensagem de boas-vindas
       $connection->send("Bem-vindo ao ServBay Workerman TCP Server!\n");
   };
   
   // Lógica para recebimento de mensagens
   // $data contém os dados TCP recebidos já processados conforme protocolo
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Dados recebidos: " . $data;
       // Ecoa os dados recebidos de volta ao cliente
       $connection->send('ServBay Workerman recebeu: ' . $data);
   };
   
   // Ao fechar conexão
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Conexão TCP encerrada\n";
   };
   
   // Rode todos os Workers
   Worker::runAll();

2. Execute o servidor TCP

   Dentro do diretório do projeto, rode:

   php tcp_server.php start

   Também pode-se usar -d para background. Depois do servidor TCP estar rodando, conecte-se usando um cliente TCP, como telnet ou nc.

   Em macOS/Linux, abra outro terminal e digite:

   # Com telnet
   telnet localhost 8082
   
   # Ou com nc (netcat)
   nc localhost 8082

   Após conectar, você verá a mensagem de boas-vindas. Envie qualquer texto seguido de Enter (o protocolo Text usa final \n) e o servidor irá ecoar a mensagem de volta.

Observações Importantes

• Ocupação de portas: Certifique-se de que as portas usadas pelo Workerman (exemplos: 8080, 8081, 8082) não estão ocupadas por outros processos no macOS ou no próprio ServBay. Se houver conflito, o Workerman não irá iniciar e retornará erro. Use lsof -i :porta para checar o uso.
• Firewall: O firewall do macOS pode bloquear acessos externos nessas portas. Em desenvolvimento local geralmente não é problema, mas se precisar acessar de outro dispositivo na rede, configure o firewall adequadamente.
• Relação com o Web Server do ServBay: O Workerman escuta suas próprias portas e roda de forma independente dos servidores Caddy ou Nginx que vêm com o ServBay. Geralmente o Workerman processa as conexões diretamente (exceto se configurar proxy reverso). É mais adequado para conexões persistentes ou aplicações altamente concorrentes (WebSocket, por exemplo). Caddy/Nginx é mais indicado para requisições HTTP tradicionais e curtas.
• Versão do PHP: Verifique se o PHP selecionado no ServBay atende ao mínimo exigido pelo Workerman. O ServBay possui várias versões de PHP, podendo alterná-las facilmente.
• Extensões PHP: Workerman depende de algumas extensões PHP para melhor desempenho, como event (se instalada, será usada para maior eficiência), posix, pcntl (para multiprocessos). O ServBay já habilita a maioria das extensões principais, mas caso note problemas, cheque no painel do ServBay se elas estão ativas para seu PHP.
• Logs: No modo daemon, as saídas do Workerman vão para arquivos de log. Monitore-os regularmente para checar erros e o funcionamento da aplicação.

Perguntas Frequentes (FAQ)

• Q: Como encerrar o servidor Workerman?
  • A: Se estiver rodando em primeiro plano (start), basta usar Ctrl+C no terminal. Se estiver em segundo plano como daemon (start -d), use php nome_do_arquivo.php stop no diretório do projeto.
• Q: Por que não consigo iniciar o servidor Workerman?
  • A: O motivo mais recorrente é porta em uso. Cheque o erro no terminal, que normalmente diz qual porta está ocupada. Troque para uma porta livre ou finalize o serviço que estiver usando a porta. Utilize o comando lsof -i :porta para descobrir qual processo está usando.
• Q: Qual a diferença entre o Caddy/Nginx do ServBay e o Workerman? Quando usar cada um?
  • A: Caddy/Nginx são servidores Web tradicionais para HTTP/HTTPS, geralmente trabalhando junto ao PHP-FPM, e o PHP processa as requisições e encerra após cada uma. O Workerman é um framework PHP assíncrono capaz de atuar como servidor HTTP próprio, além de protocolos como WebSocket/TCP, rodando permanentemente em memória — ideal para alta concorrência, conexões persistentes, aplicações em tempo real. Use o Caddy/Nginx para sites convencionais/API REST; use Workerman para chat em tempo real, backend de jogos, IoT, etc. É possível combinar os dois, por exemplo, usando proxy reverso para certas rotas.
• Q: É possível rodar múltiplas aplicações Workerman no ServBay simultaneamente?
  • A: Sim. Cada aplicação Workerman deve rodar em um processo PHP distinto e escutar em portas diferentes. Escreva scripts de inicialização separados para cada app e use um terminal por aplicação para iniciar (php seu_app.php start). Apenas garanta que cada app use uma porta exclusiva.

Resumo

Com este guia, você aprendeu como montar rapidamente projetos Workerman usando o ambiente prático do ServBay. O Workerman, graças à sua alta performance e programação assíncrona, fornece ao desenvolvedor PHP um poderoso arsenal para criar a próxima geração de aplicações de rede. Usando o Composer e o PHP já prontos do ServBay, você maximiza sua produtividade focando apenas na lógica do negócio e não na configuração de ambiente. Seja para criar web services rápidos ou aplicações WebSocket interativas em tempo real, o ServBay é o parceiro ideal para usar o Workerman no seu macOS local. Boa exploração com o Workerman!