Crear y ejecutar un proyecto Webman en ServBay

¿Qué es Webman?

Webman es un framework PHP asíncrono de alto rendimiento, construido sobre Workerman y diseñado específicamente para crear aplicaciones web concurrentes y eficientes. A diferencia de los frameworks tradicionales sincrónicos y bloqueantes, Webman utiliza un modelo de I/O basado en eventos y no bloqueante, logrando un rendimiento sobresaliente ante gran cantidad de solicitudes simultáneas. Ofrece una API limpia y fácil de usar, junto con una arquitectura flexible para expandirse, lo que lo convierte en la opción ideal para aplicaciones en tiempo real, servicios API, microservicios y más.

Principales características y ventajas de Webman

• Alto rendimiento: Basado en Workerman, aprovecha I/O asíncrono y dirigido por eventos para manejar grandes cantidades de conexiones concurrentes, superando ampliamente los frameworks tradicionales.
• Sencillo de usar: Su API intuitiva y completa funcionalidad permiten a los desarrolladores comenzar un proyecto rápidamente.
• Soporte multiprotocolo: Incorpora soporte para protocolos frecuentes como HTTP y WebSocket, facilitando la construcción de diversos tipos de servicios.
• Expansión flexible: Permite integrar fácilmente nuevas funciones mediante paquetes de Composer, plugins y middleware.
• Bajo consumo de recursos: Al operar como un proceso residente en memoria, Webman consume menos recursos comparado al tradicional modelo de servidor web + PHP-FPM.
• Comunidad activa: Cuenta con una comunidad vibrante y documentación abundante.

Webman ayuda a los desarrolladores a construir aplicaciones web y servicios API altamente escalables y veloces, especialmente en escenarios que requieren mucha concurrencia y baja latencia.

Crear y ejecutar un proyecto sencillo Webman en ServBay

Esta guía te mostrará paso a paso cómo usar Webman en el entorno local de ServBay para crear y ejecutar un proyecto web básico. Te enseñaremos a instalar Webman, escribir rutas y controladores esenciales, e integrar bases de datos (MySQL y PostgreSQL) y servicios de caché (Redis, Memcached) de ServBay.

TIP

ServBay recomienda que todos los proyectos de sitios web locales se almacenen en el directorio /Applications/ServBay/www, para facilitar la gestión centralizada y configuración de sitios web locales (antes llamado “host”).

Requisitos previos

Antes de comenzar, asegúrate de lo siguiente:

1. ServBay instalado: Debes tener ServBay correctamente instalado en macOS. ServBay ofrece un entorno local integrado con PHP, Composer, MySQL, PostgreSQL, Redis, Memcached y todos los paquetes requeridos en esta guía.
2. Paquetes necesarios habilitados: Desde el panel de control de ServBay, verifica que los siguientes paquetes estén instalados y activos:
   • La versión de PHP que elijas (recomendado PHP 8.x o superior)
   • Composer (incluido en ServBay)
   • MySQL
   • PostgreSQL
   • Redis
   • Memcached
   • Verifica que la versión seleccionada de PHP tenga habilitadas las extensiones memcached, redis, pdo_mysql, pdo_pgsql, entre otras necesarias. ServBay las habilita por defecto, pero puedes revisarlas en la configuración de PHP en ServBay.
3. Acceso a la terminal: Ten conocimientos básicos de la terminal en macOS.

Instalación de Webman

1. Verifica que Composer está disponible

   ServBay viene con Composer preinstalado y listo para usar en la terminal. Puedes comprobarlo ejecutando:

   composer --version

   Si ves la versión de Composer correctamente, está listo para usarse.

2. Accede al directorio de sitios web de ServBay

   Abre la terminal y navega al directorio raíz recomendado por ServBay:

   cd /Applications/ServBay/www

3. Crea un proyecto Webman usando Composer

   Utiliza el comando create-project para instalar Webman en el directorio elegido. En este ejemplo, el proyecto se llamará servbay-webman-app:

   composer create-project workerman/webman servbay-webman-app

   Composer descargará Webman y sus dependencias en el directorio servbay-webman-app.

4. Entra al directorio del proyecto

   Una vez terminado, cambia al directorio del nuevo proyecto:

   cd servbay-webman-app

5. Instala los componentes necesarios

   Para usar bases de datos y caché en el ejemplo, instala algunos paquetes adicionales con Composer. Webman suele utilizar illuminate/database (de Laravel), illuminate/redis y similares. El parámetro -W (--with-dependencies) permite gestionar las dependencias compatibles.

   composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper

   El comando instalará el ORM de base de datos, cliente Redis, componentes de paginación y eventos, además del depurador VarDumper.

Crear base de datos y tablas

Para que los ejemplos funcionen, necesitas crear la base de datos y la tabla users en MySQL y PostgreSQL de ServBay. Por defecto, la contraseña de usuario root en ServBay es password.

Puedes usar las herramientas de administración de bases de datos provistas por ServBay (como phpMyAdmin o pgAdmin, accesibles desde el panel) o la terminal para ejecutar estos comandos SQL.

1. Crea la base de datos webman_app

   • MySQL:

     CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   • PostgreSQL:

     CREATE DATABASE webman_app;

2. Crea la tabla users en la base de datos webman_app

   • MySQL:

     USE webman_app;
     CREATE TABLE users (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

   • PostgreSQL:

     \c webman_app; -- Conectar a la base de datos recién creada
     CREATE TABLE users (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

Escribir el código del proyecto web

A continuación, agregaremos el código necesario para definir las rutas, crear controladores e implementar la lógica de acceso a base de datos y caché.

1. Configurar rutas

   Edita el archivo config/route.php en la raíz del proyecto y agrega las siguientes rutas de ejemplo:

   <?php
   
   use Webman\Route;
   use app\controller\IndexController;
   use app\controller\CacheController;
   use app\controller\DatabaseController;
   
   // Ruta raíz, mapeada al método index de IndexController
   Route::any('/', [IndexController::class, 'index']);
   
   // Rutas de caché
   Route::any('/memcached', [CacheController::class, 'memcached']);
   Route::any('/redis', [CacheController::class, 'redis']);
   
   // Rutas de base de datos
   Route::any('/mysql-add', [DatabaseController::class, 'mysqlAdd']);
   Route::any('/mysql', [DatabaseController::class, 'mysqlGet']);
   Route::any('/pgsql-add', [DatabaseController::class, 'pgsqlAdd']);
   Route::any('/pgsql', [DatabaseController::class, 'pgsqlGet']);
   
   // Puedes agregar más rutas aquí...

2. Crear los archivos de los controladores

   Dentro del directorio app/controller, crea los archivos IndexController.php, CacheController.php y DatabaseController.php con el siguiente código.

   • app/controller/IndexController.php: Para manejar la solicitud de la ruta raíz.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response; // Importar la clase Response
     
     class IndexController
     {
         /**
          * Método de ejemplo para manejar la ruta raíz
          * @param Request $request La solicitud actual
          * @return Response Retorna un objeto Response
          */
         public function index(Request $request): Response // Especificar tipo de retorno
         {
             // Retornar respuesta de texto sencilla
             return response('Hello ServBay & Webman!'); // Mensaje de bienvenida actualizado
         }
     }

   • app/controller/CacheController.php: Para demostrar el uso de Memcached y Redis.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use Memcached; // Importar la clase Memcached
     use support\Redis; // Importar el Facade Redis de Webman
     
     class CacheController
     {
         /**
          * Demostración de uso de Memcached
          * @param Request $request
          * @return Response
          */
         public function memcached(Request $request): Response
         {
             // Conectar con Memcached en 127.0.0.1:11211 por defecto en ServBay
             $memcached = new Memcached();
             $memcached->addServer('127.0.0.1', 11211);
     
             // Establecer un ítem en caché por 60 segundos
             $success = $memcached->set('servbay_key', 'Hello Memcached from ServBay!', 60); // Clave y valor actualizados
             if (!$success) {
                  return response('Failed to set Memcached key', 500);
             }
     
             // Obtener el ítem en caché
             $value = $memcached->get('servbay_key'); // Clave actualizada
     
             // Retornar el valor obtenido
             return response($value ?: 'Memcached key not found or expired'); // Indicar si no se encuentra
         }
     
         /**
          * Demostración de uso de Redis
          * @param Request $request
          * @return Response
          */
         public function redis(Request $request): Response
         {
             // Establecer un ítem en Redis usando el Facade de Webman
             Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // Clave y valor actualizados
     
             // Obtener el ítem en Redis
             $value = Redis::get('servbay_redis_key'); // Clave actualizada
     
             // Retornar el valor obtenido
             return response($value ?: 'Redis key not found'); // Indicar si no se encuentra
         }
     }

   • app/controller/DatabaseController.php: Para demostrar operaciones en MySQL y PostgreSQL.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use support\Db; // Importar el Facade Db de Webman
     
     class DatabaseController
     {
         /**
          * Agregar usuario en MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlAdd(Request $request): Response
         {
             try {
                 // Insertar datos en 'mysql' usando Db Facade
                 Db::connection('mysql')->table('users')->insert([
                     'name' => 'ServBay Webman MySQL User', // Datos de ejemplo actualizados
                     'email' => 'mysql_demo@servbay.test', // Email actualizado
                     'created_at' => date('Y-m-d H:i:s') // Agrega created_at
                 ]);
                 return response('User added to MySQL'); // Mensaje actualizado
             } catch (\Exception $e) {
                 return response('Error adding user to MySQL: ' . $e->getMessage(), 500); // Agrega manejo de error
             }
         }
     
         /**
          * Listar usuarios en MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlGet(Request $request): Response
         {
             try {
                 // Obtener todos los usuarios de 'mysql' usando Db Facade
                 $users = Db::connection('mysql')->table('users')->get();
                 // Retornar los usuarios en formato JSON
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Especifica Content-Type
             } catch (\Exception $e) {
                  return response('Error getting users from MySQL: ' . $e->getMessage(), 500); // Agrega manejo de error
             }
         }
     
         /**
          * Agregar usuario en PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlAdd(Request $request): Response
         {
              try {
                 // Insertar datos en 'pgsql' usando Db Facade
                 Db::connection('pgsql')->table('users')->insert([
                     'name' => 'ServBay Webman PgSQL User', // Datos de ejemplo actualizados
                     'email' => 'pgsql_demo@servbay.test', // Email actualizado
                     'created_at' => date('Y-m-d H:i:s') // Agrega created_at
                 ]);
                 return response('User added to PostgreSQL'); // Mensaje actualizado
              } catch (\Exception $e) {
                 return response('Error adding user to PostgreSQL: ' . $e->getMessage(), 500); // Agrega manejo de error
              }
         }
     
         /**
          * Listar usuarios en PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlGet(Request $request): Response
         {
              try {
                 // Obtener todos los usuarios de 'pgsql' usando Db Facade
                 $users = Db::connection('pgsql')->table('users')->get();
                 // Retornar los usuarios en formato JSON
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Especifica Content-Type
              } catch (\Exception $e) {
                 return response('Error getting users from PostgreSQL: ' . $e->getMessage(), 500); // Agrega manejo de error
              }
         }
     }

3. Configurar la conexión a la base de datos

   Edita el archivo config/database.php en la raíz del proyecto, y configura los datos de conexión para MySQL y PostgreSQL. El host por defecto en ServBay es 127.0.0.1, con puertos 3306 (MySQL) y 5432 (PostgreSQL), y contraseña de usuario root es password.

   <?php
   /**
    * Configuración de base de datos
    */
   return [
       // Conexión de base de datos por defecto
       'default' => 'mysql',
   
       // Lista de configuraciones de conexión
       'connections' => [
           'mysql' => [
               'driver'    => 'mysql',
               // Host y puerto por defecto de MySQL en ServBay
               'host'      => '127.0.0.1',
               'port'      => 3306,
               // Nombre de la base de datos creada previamente
               'database'  => 'webman_app',
               // Usuario por defecto de MySQL en ServBay
               'username'  => 'root',
               // Contraseña por defecto de MySQL en ServBay
               'password'  => 'password',
               'charset'   => 'utf8mb4',
               'collation' => 'utf8mb4_unicode_ci',
               'prefix'    => '',
               'strict'    => true,
               'engine'    => null,
           ],
           'pgsql' => [
               'driver'   => 'pgsql',
               // Host y puerto por defecto de PostgreSQL en ServBay
               'host'     => '127.0.0.1',
               'port'     => 5432,
                // Nombre de la base de datos creada previamente
               'database' => 'webman_app',
                // Usuario por defecto de PostgreSQL en ServBay
               'username' => 'root',
                // Contraseña por defecto de PostgreSQL en ServBay
               'password' => 'password',
               'charset'  => 'utf8',
               'prefix'   => '',
               'schema'   => 'public',
               'sslmode'  => 'prefer', // Puede ser require, verify-ca, verify-full
           ],
           // Puedes agregar más conexiones aquí...
       ],
   ];

   Importante: En entornos de producción, cambia la contraseña por defecto de la base de datos y evita incluir credenciales sensibles en el código fuente.

Ejecutar el proyecto Webman

Webman se ejecuta habitualmente mediante el script start.php, que inicia los procesos Workerman. Esto es diferente al modo tradicional de operar con Nginx/Apache + PHP-FPM; Webman es un proceso asíncrono residente en memoria.

En la raíz del proyecto (/Applications/ServBay/www/servbay-webman-app), inicia el proyecto con:

php start.php start

Este comando mostrará la información de inicio de Webman y, por defecto, estará escuchando en 127.0.0.1:8787 para solicitudes HTTP.

• Nota: El comando php hace uso del ejecutable PHP integrado en ServBay. ServBay configura automáticamente tu entorno para poder usar PHP directo desde la terminal.
• Para ejecutar Webman en segundo plano utiliza el parámetro -d: php start.php start -d.
• Para detener el servicio ejecuta: php start.php stop.
• Para reiniciar el servicio ejecuta: php start.php restart.
• Para reiniciar de forma suave (sin interrumpir solicitudes actuales): php start.php reload.

Probar el proyecto

Una vez iniciado correctamente Webman y escuchando en 127.0.0.1:8787, puedes acceder a las siguientes URLs para probar sus funciones en el navegador:

• http://localhost:8787/: Deberás ver en pantalla Hello ServBay & Webman!.
• http://localhost:8787/memcached: Deberás ver Hello Memcached from ServBay!, indicando el éxito de la conexión y uso de Memcached.
• http://localhost:8787/redis: Deberás ver Hello Redis from ServBay!, señalando que Redis está funcionando con Webman.
• http://localhost:8787/mysql-add: Deberás ver User added to MySQL, lo que implica que se añadió un registro a la tabla users de MySQL.
• http://localhost:8787/mysql: Aparecerá un listado en formato JSON de los usuarios registrados en la tabla users de MySQL.
• http://localhost:8787/pgsql-add: Deberás ver User added to PostgreSQL, confirmando el registro en la tabla users en PostgreSQL.
• http://localhost:8787/pgsql: Aparecerá una lista en formato JSON con los usuarios de la tabla users en PostgreSQL.

Si tienes problemas al acceder a estas URLs, revisa la salida de la terminal para errores, verifica que MySQL, PostgreSQL, Redis y Memcached de ServBay estén activos y que las extensiones de PHP estén habilitadas.

Preguntas frecuentes (FAQ)

• P: ¿El comando php start.php start no se encuentra?
  • R: Verifica que estés en el directorio del proyecto servbay-webman-app en la terminal, y que PHP de ServBay esté correctamente en tu PATH (ServBay se ocupa de esto automáticamente).
• P: ¿Error de conexión al acceder a localhost:8787?
  • R: Revisa posibles errores en la terminal al ejecutar php start.php start. Asegúrate de que el puerto 8787 está libre; si está ocupado, puedes cambiar el puerto en la configuración (por ejemplo, en config/server.php).
• P: ¿Error de conexión a la base de datos?
  • R: Verifica que MySQL y PostgreSQL estén activos en ServBay. Revisa en config/database.php que host, puerto, nombre de base de datos, usuario y contraseña coincidan con la configuración de ServBay (usuario por defecto root, contraseña password). Confirma que existen la base webman_app y la tabla users.
• P: ¿Falla al conectar a Memcached o Redis?
  • R: Comprueba que Memcached y Redis estén activos en ServBay. Verifica las direcciones y puertos en app/controller/CacheController.php: por defecto 127.0.0.1:11211 para Memcached y 127.0.0.1:6379 para Redis. Revisa que la versión de PHP tenga habilitadas las extensiones memcached y redis.

Resumen

Siguiendo estos pasos, has creado, configurado y ejecutado exitosamente un proyecto básico Webman en el entorno de desarrollo local de ServBay. Aprendiste a aprovechar la integración de ServBay para montar rápidamente el entorno de Webman e incluir funcionalidades avanzadas con base de datos y caché. La alta eficiencia de Webman combinada con la comodidad de ServBay ofrecen una plataforma robusta para el desarrollo de tus aplicaciones PHP asíncronas. Esperamos que esta guía te ayude a sacar el mayor provecho de ServBay y Webman para crear aplicaciones web sobresalientes.