Configuración y ejecución de aplicaciones Workerman en ServBay

Resumen

Este documento tiene como objetivo guiar a los usuarios de ServBay sobre cómo crear y ejecutar rápidamente aplicaciones de red asíncronas y de alto rendimiento en macOS, aprovechando el entorno PHP integrado y Composer incluidos en ServBay. Workerman es una potente librería PHP ideal para construir servicios de red que requieren alto procesamiento de concurrencia, como servidores web, servidores de comunicación en tiempo real, servidores de juegos, entre otros. ServBay ofrece una plataforma lista para usar que simplifica en gran medida el proceso de configuración de Workerman.

¿Qué es Workerman?

Workerman es un marco de comunicación de red asíncrona y de alto rendimiento completamente escrito en PHP, y de código abierto. Funciona sobre EventLoop y emplea E/S no bloqueante y asíncrona, permitiendo gestionar eficientemente una gran cantidad de conexiones concurrentes. A diferencia del desarrollo web tradicional en PHP (por ejemplo, Apache/Nginx + PHP-FPM), las aplicaciones Workerman suelen ejecutarse en memoria permanente, escuchando puertos específicos y gestionando directamente las conexiones y datos, para así evitar la sobrecarga de la destrucción de procesos tras cada solicitud y lograr un gran aumento en el rendimiento y el procesamiento de solicitudes.

Con Workerman, los desarrolladores pueden crear fácilmente:

• Servidores HTTP de alto rendimiento, incluso reemplazando Apache/Nginx para peticiones estáticas o dinámicas simples.
• Servidores WebSocket en tiempo real, ideales para chat en línea, envío de datos en tiempo real, entre otros.
• Servidores TCP/UDP con protocolos personalizados.
• Herramientas de línea de comandos, tareas programadas, microservicios, etc.

Características clave y ventajas de Workerman

• Alto rendimiento: Basado en un núcleo orientado a eventos y E/S asíncrona no bloqueante, capaz de manejar una gran cantidad de conexiones concurrentes y ofrecer un rendimiento excepcional.
• Soporte de múltiples protocolos: Incluye soporte nativo para HTTP, WebSocket, TCP, UDP, entre otros, y provee interfaces flexibles para que los desarrolladores implementen protocolos personalizados.
• Facilidad de uso: Su API es sencilla e intuitiva, lo que reduce la complejidad de la programación de red asíncrona; los programadores PHP pueden comenzar a usarlo rápidamente.
• Extensible y flexible: Soporta un modelo multiproceso que permite el escalado horizontal y balanceo de carga aprovechando CPUs multicore. Se puede integrar fácilmente con paquetes Composer y librerías PHP existentes.
• Integración con el ecosistema PHP: Como una librería PHP, se fusiona perfectamente con el ecosistema, permitiendo la gestión de dependencias vía Composer.
• Modo demonio: Soporta ejecución en segundo plano como proceso demonio, ideal para entornos de producción y para asegurar la alta disponibilidad del servicio.

Workerman habilita a los desarrolladores PHP para construir aplicaciones de red en tiempo real, de alta concurrencia y alto rendimiento.

Configuración del entorno de desarrollo Workerman con ServBay

ServBay es una herramienta pensada para desarrolladores web que integra entornos de ejecución de idiomas como PHP, Node.js, Python, Go, Java, así como servidores y bases de datos populares: Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached, entre otros. Su mayor fortaleza es su facilidad de uso inmediato, especialmente al traer Composer preconfigurado, lo que facilita enormemente crear y ejecutar proyectos Workerman en ServBay.

Esta guía mostrará cómo montar y ejecutar aplicaciones Workerman rápidamente en ServBay mediante varios ejemplos básicos: un servidor HTTP simple, un servidor WebSocket y un servidor TCP.

TIP

Para una mejor gestión y organización, ServBay recomienda almacenar todos los proyectos web locales en el directorio /Applications/ServBay/www. Todas las rutas ejemplificadas en este documento asumen este directorio.

Requisitos previos

Antes de comenzar, asegúrate de lo siguiente:

1. ServBay instalado y en funcionamiento: Descarga e instala la última versión desde el sitio oficial de ServBay.
2. PHP habilitado en ServBay: Desde el panel de control de ServBay, asegúrate de que la versión de PHP que deseas usar esté activada. Workerman requiere PHP 5.4 o superior, siendo recomendable PHP 7.x u 8.x para obtener el mejor rendimiento.
3. Conocimientos básicos de PHP y línea de comandos: Debes comprender la sintaxis fundamental de PHP y cómo usar herramientas de línea de comandos en la terminal.

Instalación de Workerman

1. Asegurar la disponibilidad de Composer

ServBay ya incluye Composer, por lo que no es necesario instalarlo aparte. Solo asegúrate de que ServBay esté ejecutándose y que la versión de PHP que vayas a usar esté habilitada. ServBay configura automáticamente Composer para esa versión de PHP. Puedes acceder al entorno PHP de ServBay usando su terminal integrada o una terminal externa (si ServBay añadió PHP y Composer al PATH del sistema).

Abre una terminal y verifica que Composer esté disponible con el siguiente comando:

composer -v

Si Composer está correctamente instalado y configurado en el entorno PHP de ServBay, verás la información de su versión. Si el comando no se encuentra, revisa que ServBay esté en ejecución y que PHP esté habilitado.

2. Crear el directorio del proyecto

Navega al directorio raíz recomendado por ServBay y crea un nuevo directorio para el proyecto, luego accede a él:

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

Aquí hemos creado un directorio llamado servbay-workerman-demo para alojar los archivos del proyecto Workerman.

3. Instalar Workerman usando Composer

Dentro del directorio del proyecto (/Applications/ServBay/www/servbay-workerman-demo), instala la librería Workerman con Composer. Esta es la manera recomendada porque Composer gestionará automáticamente las dependencias:

composer require workerman/workerman

Composer descargará Workerman y sus dependencias en el directorio vendor.

Escribir el código de un servidor HTTP con Workerman

El servidor HTTP es uno de los usos más comunes de Workerman y puede ser la base para aplicaciones web o servicios API de alto rendimiento.

Crea un archivo llamado http_server.php (u otro de tu preferencia, por ejemplo server.php) en el directorio del proyecto, y agrega el siguiente código PHP:

<?php
// Incluir el autoload de Composer para cargar las clases de Workerman
require __DIR__ . '/vendor/autoload.php';

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

// Crear una instancia de Worker y especificar protocolo y dirección
// 'http://0.0.0.0:8080' crea un servidor HTTP escuchando en el puerto 8080 de todas las interfaces (0.0.0.0)
// 0.0.0.0 permite el acceso desde la máquina local o cualquier equipo de la red local; 8080 es el número de puerto escuchado
$http_worker = new Worker('http://0.0.0.0:8080');

// Establecer el número de procesos Worker
// Aquí se ponen 4, lo que inicia 4 procesos PHP independientes para manejar las solicitudes; ajustable por número de núcleos de CPU
$http_worker->count = 4;

// Definir la lógica al recibir un mensaje del cliente (petición HTTP)
// $connection es el objeto de conexión actual y permite enviar respuestas al cliente
// $request es el objeto de la petición, que incluye información detallada (URL, headers, cuerpo, etc.)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Enviar una respuesta HTTP simple al cliente
    // Workerman maneja automáticamente cabeceras y detalles del protocolo HTTP
    $connection->send(new Response(200, [], '¡Hola ServBay Workerman HTTP Server!'));
};

// Ejecutar todas las instancias Worker
// Este es el ciclo principal de Workerman; al iniciarlo, los procesos empiezan a escuchar el puerto y a procesar eventos
Worker::runAll();

Explicación del código:

• require __DIR__ . '/vendor/autoload.php';: Carga el autoload generado por Composer, permitiendo incluir clases como Worker, Request, Response, etc.
• use Workerman\...;: Importa las clases necesarias.
• new Worker('http://0.0.0.0:8080'): Crea una instancia de Workerman. El parámetro define el protocolo (http) y la dirección (0.0.0.0:8080).
• $http_worker->count = 4;: Establece el número de procesos que Workerman utilizará. Más procesos aprovechan CPUs multinúcleo y mejoran la concurrencia.
• $http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };: Define el callback que se ejecuta cuando Workerman recibe una petición HTTP completa. $connection se usa para responder al cliente, y $request contiene información de la petición. Response permite crear una respuesta estándar HTTP.
• Worker::runAll();: Inicia el bucle de eventos de Workerman y empieza a escuchar peticiones con todas las instancias Worker.

Ejecutar el servidor HTTP de Workerman

Desde el directorio del proyecto (/Applications/ServBay/www/servbay-workerman-demo), abre una terminal y ejecuta el siguiente comando para iniciar el servidor HTTP:

php http_server.php start

Modos de ejecución:

• Modo en primer plano (Foreground): Al ejecutar php http_server.php start, Workerman se ejecuta en la terminal mostrando logs e información. Puedes detenerlo con Ctrl+C. Este modo es ideal para desarrollo y pruebas.
• Modo demonio (Daemon): En producción, usualmente es necesario que Workerman corra en segundo plano. Usa la opción -d:

  php http_server.php start -d

  Workerman correrá en segundo plano y la salida se redirigirá a archivos de log (ubicados en el directorio de Workerman o en una ruta especificada).

Gestión de procesos:

Workerman proporciona varios comandos para gestión de procesos:

• Iniciar: php http_server.php start (foreground) o php http_server.php start -d (background)
• Detener: php http_server.php stop (espera que las solicitudes en curso se completen y luego cierra)
• Reiniciar: php http_server.php restart (detiene y vuelve a iniciar)
• Reinicio suave (Reload): php http_server.php reload (útil para actualizar código, reinicia procesos hijo uno por uno sin interrumpir el servicio; ten cuidado con funciones del ciclo de vida como onWorkerStart)
• Ver estado: php http_server.php status (consulta el estado de los procesos de Workerman, memoria, conexiones, etc.)

Después de iniciar el servidor, abre el navegador y accede a http://localhost:8080 o http://127.0.0.1:8080. Deberías ver en pantalla: ¡Hola ServBay Workerman HTTP Server!.

Crear un servidor WebSocket con Workerman

El protocolo WebSocket permite mantener una conexión bidireccional permanente entre el cliente y el servidor, ideal para aplicaciones en tiempo real como chats, cotizaciones en vivo, juegos, etc. Workerman tiene excelente soporte para WebSocket.

1. Crear el código del servidor WebSocket

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

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crear una instancia de servidor WebSocket en el puerto 8081
   // 'websocket://0.0.0.0:8081' crea un servidor WebSocket
   // Workerman gestiona automáticamente el handshake (apretón de manos) WebSocket
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Iniciar 4 procesos para manejar conexiones
   $ws_worker->count = 4;
   
   // Lógica al establecerse una nueva conexión
   // Se activa cuando un cliente se conecta
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nueva conexión WebSocket desde " . $connection->getRemoteIp() . "\n";
   };
   
   // Lógica al recibir mensajes
   // Se activa al recibir un mensaje WebSocket del cliente
   // $data contiene el mensaje ya decodificado
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Mensaje recibido: " . $data . "\n";
       // Eco al cliente con el mensaje recibido
       // $connection->send() codifica el mensaje como un frame WebSocket
       $connection->send('ServBay Workerman ha recibido: ' . $data);
   };
   
   // Lógica al cerrarse la conexión
   // Se activa cuando el cliente se desconecta
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Conexión WebSocket cerrada\n";
   };
   
   // Lógica ante errores (opcional)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Error: $code - $msg\n";
   };
   
   
   // Ejecutar todas las instancias Worker
   Worker::runAll();

2. Ejecutar el servidor WebSocket

   En el directorio del proyecto, ejecuta:

   php websocket_server.php start

   También puedes añadir -d para ejecutarlo en segundo plano. Una vez iniciado, usa cualquier cliente WebSocket para conectarte a ws://localhost:8081.

   Por ejemplo, desde la consola del navegador con JavaScript:

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("Conexión WebSocket abierta");
     ws.send("¡Hola desde el navegador!"); // Enviar mensaje
   };
   
   ws.onmessage = function(event) {
     console.log("Mensaje del servidor:", event.data); // Recibir respuesta
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Conexión WebSocket cerrada limpiamente, 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);
   };
   
   // Cerrar la conexión (opcional)
   // ws.close();

   Al conectarte correctamente, verás registros de la conexión en la terminal y podrás ver los mensajes eco enviados/recibidos en el navegador.

Crear un servidor TCP con Workerman

Workerman también permite crear servidores TCP de propósito general para aplicaciones sobre protocolo TCP, como backends de juegos, IoT, servicios de comunicación personalizados, etc.

1. Crear el código del servidor TCP

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

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crear una instancia de servidor TCP en el puerto 8082
   // 'tcp://0.0.0.0:8082' crea un servidor TCP
   // Workerman usa por defecto el protocolo Text (fin de línea '\n'); puedes especificar otros o usar uno personalizado
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Iniciar 4 procesos para manejar conexiones
   $tcp_worker->count = 4;
   
   // Lógica al establecerse una nueva conexión
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nueva conexión TCP desde " . $connection->getRemoteIp() . "\n";
       // Enviar mensaje de bienvenida al conectarse
       $connection->send("¡Bienvenido al Servidor TCP ServBay Workerman!\n");
   };
   
   // Lógica al recibir datos
   // $data es el mensaje recibido por TCP (tras la interpretación por protocolo)
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Datos recibidos: " . $data;
       // Eco al cliente con los datos recibidos
       $connection->send('ServBay Workerman ha recibido: ' . $data);
   };
   
   // Lógica al cerrarse la conexión
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Conexión TCP cerrada\n";
   };
   
   // Ejecutar todas las instancias Worker
   Worker::runAll();

2. Ejecutar el servidor TCP

   Desde el directorio del proyecto, ejecuta:

   php tcp_server.php start

   También puedes agregar -d para ejecutarlo como demonio. Una vez iniciado, usa una herramienta cliente TCP para conectar a localhost:8082.

   Por ejemplo, desde macOS/Linux, abre otra terminal y utiliza telnet o nc:

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

   Tras conectar, verás el mensaje de bienvenida del servidor. Escribe cualquier texto y al pulsar Enter (usa el protocolo Text), el servidor te devolverá tu mensaje.

Consideraciones importantes

• Puertos ocupados: Asegúrate de que los puertos usados por Workerman (8080, 8081, 8082 en los ejemplos) no estén siendo utilizados por macOS o por otros servicios dentro de ServBay. Si hay conflicto, Workerman arrojará un error de inicio de puerto en uso. Usa lsof -i :puerto para comprobar ocupación.
• Firewall: El firewall integrado de macOS podría bloquear accesos externos. En entorno local no suele ser un problema, pero si requieres acceso desde otros dispositivos de la red, revisa la configuración del firewall.
• Relación con servidor web ServBay: Workerman escucha en sus propios puertos y es independiente de servidores como Caddy o Nginx de ServBay. Workerman maneja las conexiones directamente, no pasando por Caddy/Nginx a menos que configures un proxy inverso explícito. Es más idóneo para conexiones largas o alta concurrencia (como WebSocket), mientras que los servidores Caddy/Nginx suelen ser para HTTP tradicionales y de corta duración.
• Versión de PHP: Verifica que la versión de PHP usada para Workerman cumpla los requisitos mínimos. ServBay incluye múltiples versiones; selecciona la adecuada desde el panel de control.
• Extensiones requeridas: Workerman depende de algunas extensiones PHP como event (si está disponible, aporta mejor rendimiento), posix, pcntl (utilizadas para el modo multiproceso). ServBay incluye la mayoría activadas, pero si encuentras problemas, revisa las extensiones para la versión de PHP correspondiente.
• Logs: En modo demonio, la salida de Workerman se escribe en archivos de log. Revisa periódicamente estos archivos para monitorizar el estado de la aplicación y posibles errores.

Preguntas frecuentes (FAQ)

• Q: ¿Cómo detengo un servidor Workerman?
  • A: Si el servidor está en primer plano (start), solo presiona Ctrl+C en la terminal. Si corre como demonio (start -d), deténlo con php tu_archivo_servidor.php stop desde el directorio del proyecto.
• Q: ¿Por qué no arranca mi servidor Workerman?
  • A: Lo más frecuente es que el puerto esté ocupado. Verifica el error en la terminal y prueba con otro puerto o detén el proceso que lo esté usando. Usa lsof -i :puerto para ver qué proceso lo utiliza.
• Q: ¿Cuál es la diferencia entre Caddy/Nginx de ServBay y Workerman? ¿Cuál debo usar?
  • A: Caddy/Nginx de ServBay son servidores web tradicionales para peticiones HTTP/HTTPS estándar, donde PHP se gestiona mediante PHP-FPM y los procesos pueden terminar tras cada petición. Workerman es un framework asincrónico de PHP capaz de funcionar como servidor HTTP, WebSocket o TCP, corriendo en memoria de forma permanente y es mejor para aplicaciones de alta concurrencia, conexiones largas o comunicación en tiempo real. Escoge según tus necesidades: para sitios web convencionales o APIs RESTful usa Caddy/Nginx; para chat en tiempo real, backends de juegos o IoT prefiere Workerman. Puedes combinar ambos, por ejemplo, usando Caddy/Nginx como proxy inverso para ciertas rutas.
• Q: ¿Puedo ejecutar varios proyectos Workerman en ServBay al mismo tiempo?
  • A: Sí. Cada aplicación Workerman corre en un proceso PHP independiente y debe escuchar en un puerto diferente. Simplemente crea scripts de inicio separados para cada app y ejecuta php tu_app_servidor.php start en diferentes terminales (o en segundo plano). Solo asegúrate de que no haya conflictos de puerto.

Resumen

Con esta guía, has aprendido cómo montar y ejecutar proyectos Workerman de forma eficiente en el entorno local ServBay. Gracias a su alto rendimiento y capacidades asíncronas, Workerman ofrece a los desarrolladores PHP una poderosa plataforma para crear la próxima generación de aplicaciones de red. Trabajando con Composer y PHP completamente integrados en ServBay, puedes aumentar tu productividad y concentrarte en la lógica de negocio de tus aplicaciones Workerman, sin perder tiempo en la configuración del entorno. Ya sea construyendo servicios web de alto rendimiento o aplicaciones WebSocket interactivas, ServBay es el aliado ideal para desarrollar con Workerman en tu entorno local. ¡Esperamos que esta documentación te ayude a iniciar tu exploración con Workerman sin contratiempos!