Cómo instalar y ejecutar aplicaciones Workerman en ServBay

Introducción

Este documento está diseñado para guiar a usuarios de ServBay en la instalación y ejecución rápida de aplicaciones PHP de alto rendimiento basadas en Workerman, aprovechando el entorno PHP y Composer integrados en ServBay, tanto en macOS como en Windows. Workerman es una potente librería PHP, ideal para construir servicios de red que requieren manejo de alta concurrencia, como servidores Web, sistemas de comunicación en tiempo real, servidores de juegos, entre otros. ServBay ofrece una plataforma de desarrollo lista para usar, lo que simplifica enormemente la configuración de entorno para Workerman.

¿Qué es Workerman?

Workerman es un framework de comunicación de red asíncrona y de alto rendimiento, escrito completamente en PHP y de código abierto. Basado en el mecanismo EventLoop (bucle de eventos), implementa I/O asíncrona no bloqueante, permitiendo gestionar eficientemente una gran cantidad de conexiones concurrentes. A diferencia del modelo tradicional de desarrollo web en PHP (por ejemplo, Apache/Nginx + PHP-FPM), las aplicaciones Workerman se ejecutan en memoria de forma persistente, escuchando puertos específicos, procesando directamente conexiones y datos de red. Esto evita la sobrecarga de iniciar y terminar procesos por cada solicitud, lo que mejora considerablemente el rendimiento y la capacidad de respuesta.

Con Workerman, los desarrolladores pueden crear fácilmente:

• Servidores HTTP de alto rendimiento, sustituyendo (incluso) a Apache/Nginx para solicitudes simples.
• Servidores WebSocket en tiempo real, para chat, transmisión de datos en vivo, etc.
• Servidores TCP/UDP con protocolos personalizados.
• Herramientas de línea de comandos, tareas programadas, microservicios, entre otros.

Características principales y ventajas de Workerman

• Alto rendimiento: Basado en arquitectura orientada a eventos y I/O asíncrona, puede manejar miles de conexiones simultáneas con gran eficiencia.
• Soporte multi-protocolo: Incluye soporte nativo para HTTP, WebSocket, TCP, UDP y permite implementar protocolos personalizados fácilmente.
• Fácil uso: Proporciona una API clara e intuitiva, simplificando la programación de redes asíncronas para desarrolladores PHP.
• Escalabilidad flexible: Soporta modelo multiproceso para aprovechar CPUs multicore optimizando la concurrencia y el balance de carga. Se integra fácilmente con paquetes Composer y librerías PHP existentes.
• Ecosistema PHP integrado: Al ser una librería PHP, se acopla perfectamente al ecosistema existente, permitiendo la gestión de dependencias con Composer de forma transparente.
• Modo daemon: Permite ejecutar los servicios en segundo plano de forma estable, ideal para ambientes productivos y garantizar la disponibilidad.

Workerman abre las puertas para que desarrolladores PHP creen aplicaciones de red modernas, de alto rendimiento y en tiempo real.

Configuración del entorno Workerman en ServBay

ServBay es una herramienta de desarrollo local pensada para desarrolladores web, que integra tiempos de ejecución para PHP, Node.js, Python, Go, Java y más, además de software de bases de datos y servidores comunes como Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached. Su principal ventaja es que funciona “lista para usar”, especialmente en lo que respecta al entorno Composer preconfigurado, facilitando enormemente la instalación y ejecución de proyectos Workerman.

Esta guía te mostrará cómo crear ejemplos básicos en ServBay para iniciar rápidamente aplicaciones Workerman: un servidor HTTP sencillo, uno WebSocket y uno TCP.

TIP

Para una gestión ordenada y estandarizada, ServBay recomienda almacenar todos los archivos de proyectos web locales bajo los siguientes directorios:

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

Todos los ejemplos de rutas de proyectos en este documento se basan en estos directorios.

Requisitos previos

Antes de empezar, asegúrate de cumplir con estos requisitos:

1. ServBay instalado y en funcionamiento: Descarga e instala la última versión desde la web oficial de ServBay.
2. PHP habilitado en ServBay: En el panel de control de ServBay, verifica que la versión de PHP que planeas usar esté activada. Workerman requiere PHP 5.4 o superior; se recomienda PHP 7.x u 8.x para mejor rendimiento.
3. Conocimientos básicos de programación PHP y comandos de consola: Familiarízate con la sintaxis básica de PHP y el uso de herramientas en terminal.

Instalación de Workerman

1. Verificar Composer

ServBay incluye Composer de forma nativa, así que no necesitas instalarlo por separado. Sólo asegúrate de que tu entorno ServBay está en marcha y la versión de PHP que usarás está activa. ServBay configura automáticamente Composer para cada versión PHP habilitada. Puedes usar Composer desde la terminal de ServBay o desde una terminal externa si ServBay ha añadido PHP y Composer al PATH del sistema.

Abre una terminal e ingresa el siguiente comando para verificar la disponibilidad de Composer:

composer -v

Si Composer está correctamente instalado y configurado en el entorno PHP de ServBay, verás información de la versión. Si el comando no se encuentra, comprueba que ServBay está ejecutándose y que la versión de PHP está activada.

2. Crear el directorio del proyecto

Navega al directorio raíz recomendado por ServBay y crea una nueva carpeta para tu proyecto, luego ingresa en ella:

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

Aquí creamos la carpeta servbay-workerman-demo para alojar los archivos de Workerman.

3. Instalar Workerman con Composer

Dentro del directorio del proyecto, instala la librería Workerman usando Composer. Este es el método recomendado; Composer gestionará todas las dependencias automáticamente.

Ruta del directorio del proyecto:

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

composer require workerman/workerman

Composer descargará Workerman y sus dependencias en la carpeta vendor del proyecto.

Crear el código de un servidor HTTP con Workerman

Un servidor HTTP es uno de los casos de uso más comunes en Workerman. Es perfecto para construir aplicaciones web o API de alto rendimiento.

En el directorio del proyecto, crea un archivo llamado http_server.php (o el nombre que prefieras, por ejemplo, server.php) y añade el siguiente código PHP:

<?php
// Incluye el archivo de autoload de Composer para acceder a las clases Workerman
require __DIR__ . '/vendor/autoload.php';

// Importa la clase Worker de Workerman
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// Crea una instancia de Worker, especificando el protocolo y dirección de escucha
// 'http://0.0.0.0:8080' crea un servidor HTTP que escucha en el puerto 8080 de todas las interfaces de red
// 0.0.0.0 permite acceso tanto local como desde otros equipos de la red
$http_worker = new Worker('http://0.0.0.0:8080');

// Define la cantidad de procesos Worker
// Aquí se usan 4 procesos PHP para manejar las solicitudes, ajusta según la cantidad de núcleos CPU
$http_worker->count = 4;

// Lógica a ejecutar cuando llega una solicitud HTTP del cliente
// $connection es el objeto de conexión para responder al cliente
// $request es el objeto de solicitud, contiene URL, encabezados, cuerpo, etc.
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Envía una cadena simple como respuesta HTTP al cliente
    // El protocolo HTTP de Workerman gestiona automáticamente los encabezados y otros detalles
    $connection->send(new Response(200, [], '¡Hola desde ServBay Workerman HTTP Server!'));
};

// Ejecuta todos los procesos Worker
// Este es el bucle principal de Workerman: inicia los procesos y comienza a escuchar el puerto
Worker::runAll();

Explicación del código:

• require __DIR__ . '/vendor/autoload.php';: Incluye el autoloader de Composer para acceder a las clases de Workerman como Worker, Request, Response.
• use Workerman\...;: Importa las clases que necesitarás.
• new Worker('http://0.0.0.0:8080'): Crea una instancia Workerman configurando el protocolo y el puerto de escucha.
• $http_worker->count = 4;: Especifica el número de procesos: más procesos permiten mejor manejo de concurrencia en CPUs multinúcleo.
• $http_worker->onMessage = function(...) { ... };: Define la función de callback para solicitudes HTTP. $connection envía datos al cliente, $request contiene los detalles de la solicitud. Response crea una respuesta HTTP estándar.
• Worker::runAll();: Activa el bucle de eventos para que los Workers comiencen a escuchar y gestionar conexiones.

Ejecutar el servidor HTTP con Workerman

En el directorio del proyecto, abre una terminal y ejecuta el siguiente comando para iniciar el servidor:

Ruta del directorio del proyecto:

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

php http_server.php start

Sobre los modos de ejecución:

• Modo en primer plano (Foreground): Al ejecutar php http_server.php start, Workerman corre en primer plano y la terminal muestra la información y los logs. Puedes detener el servidor con Ctrl+C. Este modo es útil para desarrollo y depuración.
• Modo daemon (segundo plano): En producción, se recomienda ejecutar Workerman en segundo plano usando el parámetro -d:

  php http_server.php start -d

  Workerman funcionará como proceso background y guardará los registros en un archivo de log (por defecto en el directorio de Workerman o en la ruta que indiques).

Gestión de procesos:

Workerman proporciona varios comandos para gestionar los procesos:

• Iniciar: php http_server.php start (primer plano) o php http_server.php start -d (background)
• Detener: php http_server.php stop (detiene el servidor tras finalizar solicitudes en curso)
• Reiniciar: php http_server.php restart (detiene y vuelve a iniciar el servidor)
• Recarga suave (Reload): php http_server.php reload (reinicia procesos secundarios sin interrumpir el servicio, útil para actualizaciones de código)
• Estado: php http_server.php status (verifica estado de los procesos, uso de memoria, número de conexiones, etc.)

Tras iniciar el servidor, abre tu navegador y accede a http://localhost:8080 o http://127.0.0.1:8080. Deberías ver el mensaje ¡Hola desde ServBay Workerman HTTP Server!.

Crear un servidor WebSocket con Workerman

El protocolo WebSocket permite establecer una conexión bidireccional y persistente entre cliente y servidor, ideal para aplicaciones en tiempo real como chat en línea, cotizaciones bursátiles o videojuegos. Workerman ofrece soporte nativo para WebSocket.

1. Crear el código del servidor WebSocket

   En el directorio del proyecto, crea el archivo websocket_server.php y añade lo siguiente:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea una instancia de servidor WebSocket en el puerto 8081
   // 'websocket://0.0.0.0:8081' configura el servidor en el puerto designado
   // Workerman gestiona automáticamente el handshake de WebSocket
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Arranca 4 procesos para manejar las conexiones
   $ws_worker->count = 4;
   
   // Callback cuando se establece una nueva conexión
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nueva conexión WebSocket desde " . $connection->getRemoteIp() . "\n";
   };
   
   // Callback para manejo de mensajes recibidos
   // Cuando el servidor recibe un mensaje de WebSocket desde el cliente
   // $data contiene el mensaje ya decodificado
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Mensaje recibido: " . $data . "\n";
       // Devuelve el mensaje recibido al cliente
       // $connection->send() codifica automáticamente el mensaje como frame WebSocket
       $connection->send('ServBay Workerman recibió: ' . $data);
   };
   
   // Callback cuando la conexión se cierra
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Conexión WebSocket cerrada\n";
   };
   
   // Callback en caso de errores (opcional)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Error: $code - $msg\n";
   };
   
   // Ejecuta todos los Workers
   Worker::runAll();

2. Ejecutar el servidor WebSocket

   En el directorio del proyecto ejecuta el siguiente comando para iniciar el servidor WebSocket:

   php websocket_server.php start

   Puedes también utilizar el parámetro -d para ejecutarlo en background. Tras iniciar el servidor, puedes conectar un cliente WebSocket a ws://localhost:8081.

   Por ejemplo, en la consola de desarrollador de tu navegador, prueba el siguiente código JavaScript:

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("Conexión WebSocket abierta");
     ws.send("¡Hola desde el navegador!"); // Envía mensaje
   };
   
   ws.onmessage = function(event) {
     console.log("Mensaje del servidor:", event.data); // Recibe respuesta
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Conexión WebSocket cerrada correctamente, código=" + event.code + " motivo=" + event.reason);
     } else {
       console.error("La conexión WebSocket se perdió");
     }
   };
   
   ws.onerror = function(error) {
     console.error("Error WebSocket:", error);
   };
   
   // Para cerrar la conexión manualmente (opcional)
   // ws.close();

   Tras conectar, verás mensajes de estado en tu terminal; al enviar mensajes, el servidor te devolverá la respuesta y el navegador la mostrará en pantalla.

Crear un servidor TCP con Workerman

Workerman también permite crear servidores TCP personalizados para aplicaciones como backends de juegos, plataformas IoT o servicios de comunicación especializados.

1. Crear el código del servidor TCP

   En el directorio del proyecto, crea el archivo tcp_server.php y agrega el siguiente código:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea una instancia de servidor TCP para el puerto 8082
   // 'tcp://0.0.0.0:8082' inicializa el servidor en ese puerto
   // Por defecto utiliza protocolo Text (fin de línea '\n'), puedes usar otro o personalizar
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Arranca 4 procesos para manejar las conexiones
   $tcp_worker->count = 4;
   
   // Callback cuando se establece una nueva conexión TCP
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nueva conexión TCP desde " . $connection->getRemoteIp() . "\n";
       // Envía mensaje de bienvenida al conectar
       $connection->send("¡Bienvenido al Servidor TCP de ServBay Workerman!\n");
   };
   
   // Callback para recepción de datos TCP
   // $data contiene los datos recibidos ya procesados según el protocolo
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Datos recibidos: " . $data;
       // Devuelve el dato recibido al cliente
       $connection->send('ServBay Workerman recibió: ' . $data);
   };
   
   // Callback cuando la conexión se cierra
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Conexión TCP cerrada\n";
   };
   
   // Ejecuta todos los Workers
   Worker::runAll();

2. Ejecutar el servidor TCP

   En el directorio del proyecto ejecuta el siguiente comando para iniciar el servidor TCP:

   php tcp_server.php start

   También puedes usar el parámetro -d para modo daemon. Una vez iniciado, utiliza una herramienta cliente TCP para conectarte a localhost:8082.

   Por ejemplo, desde otra terminal usa telnet o nc:

   # Usando telnet
   telnet localhost 8082
   
   # O usando nc (netcat)
   nc localhost 8082

   Al conectar, recibirás el mensaje de bienvenida. Escribe cualquier texto (finaliza con Enter, pues usa protocolo Text). El servidor responderá con el eco del mensaje enviado.

Consideraciones

• Puertos ocupados: Asegúrate de que los puertos utilizados (8080, 8081, 8082 en los ejemplos) no estén siendo usados por otros programas de macOS o de ServBay. Si existe conflicto, Workerman no podrá iniciarse y mostrará un error. Usa lsof -i :puerto para verificar el estado de los puertos.
• Firewall: El firewall del sistema puede impedir el acceso externo a estos puertos. En desarrollo local no suele haber problema, pero si necesitas acceso desde la red local revisa la configuración del firewall.
• Workerman vs. servidores web ServBay: Workerman corre en puertos propios como un proceso independiente; no depende de Caddy o Nginx de ServBay (a menos que configures un proxy reverso). Es mejor para escenarios de conexiones largas y alta concurrencia (como WebSocket), mientras que Caddy/Nginx gestiona conexiones web convencionales.
• Versión de PHP: Verifica que la versión de PHP configurada en ServBay cumple los requisitos mínimos de Workerman. ServBay incluye varias versiones; elige la más adecuada desde su panel.
• Extensiones PHP: Workerman depende de ciertas extensiones para máximo rendimiento (como event, posix, pcntl). ServBay activa la mayoría por defecto; si tienes problemas, revisa el panel de extensiones de ServBay para PHP.
• Logs: En modo daemon, la salida de Workerman se redirige a los archivos de log. Revisa los logs periódicamente para monitorear el estado y errores potenciales.

Preguntas frecuentes (FAQ)

• ¿Cómo detengo el servidor Workerman?
  • Si corre en primer plano (comando start), pulsa Ctrl+C en la terminal. Si corre en background (start -d), usa el comando php nombre_del_servidor.php stop en el directorio del proyecto.
• ¿Por qué no se inicia el servidor Workerman?
  • Habitualmente, el puerto de escucha está ocupado. Verifica el mensaje de error en la terminal. Usa otro puerto disponible o libera el puerto ocupado. El comando lsof -i :puerto te ayuda a encontrar el proceso que lo ocupa.
• ¿Cuál es la diferencia entre Caddy/Nginx de ServBay y Workerman? ¿Cuál debería elegir?
  • Caddy/Nginx son servidores web tradicionales para solicitudes HTTP/HTTPS estándar; suelen trabajar con PHP-FPM y los procesos PHP se gestionan por solicitud. Workerman es un framework PHP asíncrono que puede actuar como servidor HTTP, WebSocket, TCP, etcétera, trabajando en memoria y es ideal para aplicaciones de alta concurrencia y conexiones persistentes o en tiempo real. Elige según tus necesidades: webs convencionales y APIs REST usan Caddy/Nginx; chat en tiempo real, juegos, IoT prefieren Workerman. Puedes combinar ambos usando proxies reversos.
• ¿Puedo ejecutar múltiples aplicaciones Workerman en ServBay?
  • Sí. Cada aplicación Workerman necesita correr en un proceso PHP independiente y escuchar puertos distintos. Escribe scripts de inicio separados y ejecútalos en diferentes ventanas de terminal (o en segundo plano) asegurándote de no compartir puertos entre ellas.

Conclusión

Con esta guía ya sabes cómo instalar y ejecutar proyectos Workerman en el entorno eficiente de ServBay. Workerman, gracias a su rendimiento y arquitectura asíncrona, brinda a los desarrolladores PHP potencia para diseñar aplicaciones de red de última generación. Al combinarlo con el entorno “lista para usar” de ServBay, Composer y PHP, puedes centrarte en la lógica de negocio sin perder tiempo en configuraciones complejas. Ya sea para servidores web de alto rendimiento o aplicaciones interactivas en tiempo real, ServBay es tu aliado ideal para el desarrollo local con Workerman. ¡Esperamos que estas instrucciones te ayuden a comenzar tu aventura con Workerman sin problemas!