Configurando e Executando Aplicações Workerman no ServBay

Visão Geral

Este documento tem como objetivo orientar usuários do ServBay sobre como montar e executar aplicações de rede assíncrona de alto desempenho baseadas em Workerman usando o ambiente integrado de PHP e Composer do ServBay, em ambientes macOS e Windows. O Workerman é uma poderosa biblioteca PHP ideal para construir serviços de rede com alta demanda de concorrência, como servidores Web, comunicação em tempo real e servidores de jogos. O ServBay oferece uma plataforma pronta para uso, tornando a configuração do ambiente Workerman simples e rápida.

O Que é Workerman?

Workerman é um framework open source de comunicação de rede assíncrona de alto desempenho, totalmente escrito em PHP. Com base no mecanismo de EventLoop, implementa I/O não bloqueante e assíncrono, capaz de lidar eficientemente com milhares de conexões simultâneas. Diferente do modelo tradicional de desenvolvimento web em PHP (ex: Apache/Nginx + PHP-FPM), aplicações Workerman normalmente ficam residentes na memória, escutando portas específicas e processando diretamente conexões e dados de rede. Assim, evitam o custo de destruição de processos após cada requisição do modelo tradicional, resultando em desempenho e throughput muito superiores.

Com o Workerman, os desenvolvedores podem facilmente criar:

• Servidores HTTP de alto desempenho, capazes até mesmo de substituir Apache/Nginx em requisições simples.
• Servidores WebSocket em tempo real para aplicativos como chats, push de dados etc.
• Servidores TCP/UDP para protocolos personalizados.
• Ferramentas de linha de comando, tarefas agendadas, microsserviços e mais.

Principais Características e Vantagens do Workerman

• Alto desempenho: Núcleo baseado em eventos e I/O assíncrono, capaz de suportar milhares de conexões simultâneas com excelente performance.
• Suporte múltiplo de protocolos: Compatível nativamente com HTTP, WebSocket, TCP, UDP, entre outros, além de interfaces flexíveis para implementação de protocolos customizados.
• Fácil de usar: APIs simples e intuitivas tornam o desenvolvimento de aplicações assíncronas acessível a desenvolvedores PHP.
• Expansão flexível: Suporte a modelo multiprocessos, aproveitando CPUs multi-core para escalabilidade horizontal e balanceamento de carga. Integra facilmente pacotes Composer e bibliotecas PHP.
• Integrado ao ecossistema PHP: Por ser uma biblioteca PHP, integra-se perfeitamente a outras soluções PHP e ao Composer.
• Modo daemon: Possibilidade de rodar como daemon em segundo plano, estável para ambientes produtivos, garantindo alta disponibilidade dos serviços.

O Workerman abre portas para desenvolvedores PHP construirema aplicações de rede de alto desempenho, em tempo real e alta concorrência.

Preparando o Ambiente Workerman com ServBay

O ServBay é uma ferramenta local para desenvolvedores web, integrando runtimes de linguagens como PHP, Node.js, Python, Go, Java e diversos bancos e servidores como Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached. Seu grande diferencial é o ambiente pronto para uso, especialmente com Composer já integrado e configurado, facilitando a criação e execução de projetos Workerman.

Neste guia, mostramos exemplos básicos de como criar e rodar aplicações Workerman no ServBay: um simples servidor HTTP, um servidor WebSocket e um servidor TCP.

TIP

Para organização e padronização, o ServBay recomenda que todos os arquivos dos projetos locais fiquem nos seguintes diretórios:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Todos os exemplos de caminhos neste documento usam esse diretório base.

Pré-requisitos

Certifique-se dos seguintes pontos antes de começar:

1. ServBay instalado e funcionando corretamente: Baixe e instale a versão mais recente na página oficial do ServBay.
2. PHP habilitado no ServBay: No painel de controle do ServBay, confira se a versão de PHP desejada está ativada. O Workerman requer PHP 5.4+, sendo recomendada a 7.x ou 8.x para melhor desempenho.
3. Conhecimento básico de PHP e CLI: Entenda sintaxe PHP e saiba operar comandos no terminal.

Instalando o Workerman

1. Conferindo o Composer

O ServBay já traz Composer integrado, sem necessidade de instalação adicional. Basta ter o ServBay rodando e a versão de PHP habilitada. Composer é automaticamente configurado para cada versão de PHP no ServBay. Você pode usar o terminal do ServBay ou um terminal comum (com PHP/Composer adicionados ao PATH do sistema) para acessar o Composer.

Abra o terminal e execute:

composer -v

Se Composer estiver instalado corretamente no ambiente PHP do ServBay, será exibida a versão. Caso contrário, verifique se o ServBay está rodando e se PHP está habilitado.

2. Criando o Diretório do Projeto

Vá para o diretório raiz sugerido pelo ServBay, crie e acesse o novo diretório do projeto:

macOS:

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

Windows:

cd C:\ServBay\www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

O diretório servbay-workerman-demo conterá os arquivos do projeto Workerman.

3. Instalando o Workerman via Composer

Dentro do diretório do projeto, instale o Workerman usando o Composer. Esta é a maneira recomendada, pois o Composer gerencia todas as dependências automaticamente.

Caminho do projeto:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

composer require workerman/workerman

O Composer baixará o Workerman e dependências para a pasta vendor do projeto.

Criando o Código do Servidor HTTP Workerman

O servidor HTTP é um dos cenários mais comuns para Workerman, ideal para aplicações web ou APIs de alto desempenho.

No diretório do projeto, crie o arquivo http_server.php (ou o nome de sua preferência, como server.php) com o seguinte código PHP:

<?php
// Inclui o autoload do Composer para uso das classes Workerman
require __DIR__ . '/vendor/autoload.php';

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

// Cria uma instância Worker ouvindo o protocolo e endereço definidos
// 'http://0.0.0.0:8080' cria um servidor HTTP escutando todas interfaces locais na porta 8080
// 0.0.0.0 permite acesso da máquina local ou outros dispositivos na LAN; 8080 é a porta.
$http_worker = new Worker('http://0.0.0.0:8080');

// Define o número de processos Worker
// Aqui, 4 processos PHP independentes para lidar com as requisições. Ajuste conforme os núcleos de CPU.
$http_worker->count = 4;

// Lógica para tratar mensagens/requests dos clientes
// $connection é o objeto de conexão usado para responder ao cliente
// $request contém detalhes da requisição (URL, headers, corpo etc)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Envia uma resposta simples como resposta HTTP
    // O protocolo HTTP do Workerman cuida dos detalhes dos headers automaticamente
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// Inicia todos os Workers
// Loop principal do Workerman, os processos passam a escutar a porta e eventos após o start
Worker::runAll();

Explicação do código:

• require __DIR__ . '/vendor/autoload.php';: Carrega o autoload do Composer, tornando as classes Workerman utilizáveis.
• use Workerman\...;: Importa as classes necessárias.
• new Worker('http://0.0.0.0:8080'): Cria o servidor Workerman para protocolo HTTP e IP:Porta informados.
• $http_worker->count = 4;: Define o número de processos. Maior número = maior uso de núcleos de CPU e melhor concorrência.
• $http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };: Função executada ao receber requisições HTTP, usando $connection para responder e $request para acessar detalhes da requisição.
• Worker::runAll();: Inicia o loop de eventos Workerman e os Workers definidos.

Executando o Servidor HTTP Workerman

No diretório do projeto, abra o terminal e execute:

Caminho do projeto:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

php http_server.php start

Modos de execução:

• Foreground (Em primeiro plano): Executando php http_server.php start, o servidor roda no terminal, mostrando logs e informações. Use Ctrl+C para parar. Indicada para desenvolvimento/testes.
• Daemon (Em segundo plano): Em produção, execute com -d para rodar como daemon:

  php http_server.php start -d

  O servidor ficará em segundo plano e as saídas vão para arquivos de log.

Gerenciamento de processos:

Workerman oferece comandos práticos para gestão:

• Iniciar: php http_server.php start (foreground) ou php http_server.php start -d (daemon)
• Parar: php http_server.php stop (encerra os requests e sai graciosamente)
• Reiniciar: php http_server.php restart (para e inicia novamente)
• Reload: php http_server.php reload (reinicia processos individualmente, útil para atualizar código sem interromper serviço. Atenção à função onWorkerStart)
• Status: php http_server.php status (exibe status run-time, memória, conexões etc)

Com o servidor iniciado, acesse http://localhost:8080 ou http://127.0.0.1:8080 no navegador. Você verá Hello ServBay Workerman HTTP Server! como saída.

Criando um Servidor WebSocket com Workerman

WebSocket permite comunicação bidirecional persistente entre cliente e servidor, sendo ideal para apps em tempo real como chats, cotação de ações, jogos, etc. Workerman possui excelente suporte WebSocket.

1. Criando o código do servidor WebSocket

   No diretório do projeto, crie websocket_server.php e insira:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Cria servidor WebSocket escutando porta 8081
   // 'websocket://0.0.0.0:8081' define o protocolo WebSocket
   // Handshake do WebSocket é gerenciado pelo Workerman
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Inicializa 4 processos para tratar as conexões
   $ws_worker->count = 4;
   
   // Lógica ao estabelecer novas conexões
   // Executado quando um cliente se conecta
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nova conexão WebSocket de " . $connection->getRemoteIp() . "\n";
   };
   
   // Lógica ao receber mensagens
   // Executado quando o servidor recebe dados do cliente via WebSocket
   // $data contém a mensagem decodificada enviada pelo cliente
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Mensagem recebida: " . $data . "\n";
       // Ecoa a mensagem recebida de volta ao cliente
       // $connection->send() automaticamente codifica em frames WebSocket
       $connection->send('ServBay Workerman recebeu: ' . $data);
   };
   
   // Lógica ao fechar a conexão
   // Executado 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";
   };
   
   // Inicia o servidor
   Worker::runAll();

2. Executando o servidor WebSocket

   No diretório do projeto, rode:

   php websocket_server.php start

   Você pode também usar o modo daemon (-d). Após o start, conecte-se ao ws://localhost:8081 usando ferramentas WebSocket.

   Exemplo: no navegador, utilize o Console JavaScript para testar:

   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 mensagem
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Conexão WebSocket encerrada normalmente, código=" + event.code + " motivo=" + event.reason);
     } else {
       console.error("Conexão WebSocket perdida");
     }
   };
   
   ws.onerror = function(error) {
     console.error("Erro WebSocket:", error);
   };
   
   // Fechar conexão (opcional)
   // ws.close();

   Ao conectar, você verá informações no terminal, e mensagens serão ecoadas do servidor ao navegador.

Criando um Servidor TCP com Workerman

Workerman também permite criar servidores TCP para diversas aplicações, como backends de jogos, plataformas IoT, serviços customizados/comunicação.

1. Código do servidor TCP

   Crie tcp_server.php no diretório do projeto:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Cria servidor TCP escutando porta 8082
   // 'tcp://0.0.0.0:8082' cria o servidor TCP
   // Por padrão, usa o protocolo Text (fim de linha '\n'), podendo ser alterado para outros protocolos ou customizado
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Inicializa 4 processos para tratar as conexões
   $tcp_worker->count = 4;
   
   // Lógica ao conectar
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nova conexão TCP de " . $connection->getRemoteIp() . "\n";
       // Envia mensagem de boas-vindas ao conectar
       $connection->send("Bem-vindo ao ServBay Workerman TCP Server!\n");
   };
   
   // Lógica ao receber dados
   // $data corresponde aos dados TCP (após parse do protocolo)
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Dados recebidos: " . $data;
       // Ecoa os dados recebidos ao cliente
       $connection->send('ServBay Workerman recebeu: ' . $data);
   };
   
   // Lógica ao fechar a conexão
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Conexão TCP encerrada\n";
   };
   
   // Inicia os Workers
   Worker::runAll();

2. Executando o servidor TCP

   No diretório do projeto, execute:

   php tcp_server.php start

   Pode utilizar também o modo daemon (-d). Para testar, conecte usando um cliente TCP para o localhost:8082.

   Exemplo: abra outro terminal e digite:

   # Via telnet
   telnet localhost 8082
   
   # Ou usando nc (netcat)
   nc localhost 8082

   Após conectar, você verá a mensagem de boas-vindas do servidor. Tudo que digitar (seguido de Enter) será ecoado pelo servidor, pois o padrão é o protocolo Text.

Observações Importantes

• Portas ocupadas: Certifique-se que as portas usadas pelo Workerman (8080, 8081, 8082 nos exemplos) não estejam em uso por outros aplicativos ou pelo ServBay. Em caso de conflito, Workerman não inicia. Use o comando lsof -i :porta para verificar conflitos.
• Firewall: Firewalls do seu sistema podem bloquear conexões externas nessas portas. Em ambiente local normalmente não é problema, mas para acessos via LAN será necessário configurar o firewall.
• Independência dos servidores Web do ServBay: O Workerman escuta suas próprias portas, funcionando independente dos processos Caddy ou Nginx do ServBay. Estes são servidores web tradicionais, enquanto Workerman trata conexões diretamente (exceto se utilizar proxy reverso). Workerman é indicado para cenários de alta concorrência, conexões longas (WebSocket), enquanto ServBay (Caddy/Nginx) é ideal para requisições HTTP convencionais.
• Versão do PHP: Certifique-se de que sua versão do PHP no ServBay está conforme os requisitos mínimos do Workerman. O ServBay possui múltiplas versões do PHP, selecionáveis via painel.
• Dependências de extensões: Workerman pode aproveitar extensões PHP como event (usada para melhorar desempenho, se disponível), posix, pcntl (para multiprocessos). O ServBay já disponibiliza grande parte delas, mas confira se estão ativas no painel caso encontre problemas.
• Logs: Em modo daemon, a saída do Workerman vai para arquivos de log. Consulte estes arquivos regularmente para monitorar o status do app e possíveis erros.

FAQ (Perguntas Frequentes)

• Q: Como parar o servidor Workerman?
  • A: No modo foreground (start), use Ctrl+C no terminal. No modo daemon (start -d), rode php seu_arquivo_servidor.php stop no diretório do projeto para parar.
• Q: Por que o Workerman não inicia?
  • A: O motivo mais comum é porta ocupada. Veja a mensagem de erro no terminal para identificar. Troque a porta ou pare o processo que está ocupando a porta. Use lsof -i :porta para verificar.
• Q: Diferença entre Caddy/Nginx do ServBay e Workerman? Qual escolher?
  • A: Caddy/Nginx no ServBay são servidores HTTP/HTTPS convencionais, normalmente rodando com PHP-FPM (processos terminam ao final de cada requisição). Workerman é um framework assíncrono para PHP que pode funcionar como servidor HTTP próprio ou WebSocket/TCP, mantendo PHP residente em memória, correto para aplicações de alta concorrência, conexões longas, comunicação em tempo real. Use Caddy/Nginx para websites/APIs REST; Workerman para chat, backend de jogos, IoT etc. Pode usá-los juntos, por exemplo, montando um proxy reverso do Caddy/Nginx para Workerman.
• Q: Posso rodar múltiplas aplicações Workerman ao mesmo tempo no ServBay?
  • A: Sim. Cada aplicação Workerman deve rodar em seu próprio processo PHP e escutar portas diferentes. Basta criar scripts de inicialização separados e rodar cada um em terminais diferentes ou em modo daemon. Verifique para evitar conflito de portas.

Conclusão

Com este guia, você aprendeu como criar e executar projetos Workerman usando o ambiente local robusto do ServBay. Com desempenho elevado e recursos assíncronos, o Workerman fornece um poderoso arsenal para desenvolvedores PHP criarem aplicações de rede de próxima geração. Aliado ao ambiente pronto do ServBay – PHP e Composer configurados out-of-the-box – seu foco pode ser inteiramente no negócio da aplicação Workerman, sem perder tempo com a configuração de ambiente. Seja para criar webservices de alto desempenho ou sistemas de interação em tempo real via WebSocket, o ServBay é seu parceiro ideal para desenvolver com Workerman localmente. Esperamos que este guia o ajude a iniciar sua jornada com Workerman!