Crear y Ejecutar un Proyecto FuelPHP en el Entorno de Desarrollo Local de ServBay

¿Qué es FuelPHP?

FuelPHP es un framework PHP flexible y modular diseñado para crear aplicaciones web modernas. Adopta el patrón de diseño Modelo-Vista-Controlador Jerárquico (HMVC) y ofrece un rico conjunto de funcionalidades y herramientas que ayudan a los desarrolladores a construir aplicaciones web de alta calidad de manera rápida y eficiente. Destaca por su gran flexibilidad, alto rendimiento y facilidad de extensibilidad, lo que lo convierte en la opción preferida para muchos desarrolladores PHP.

Principales características y ventajas de FuelPHP

• Arquitectura HMVC: Soporta el patrón HMVC, facilitando la organización, reutilización y desarrollo modular del código. Es ideal para proyectos grandes o de complejidad elevada.
• Alto desempeño: FuelPHP está optimizado para ofrecer un rendimiento sobresaliente, procesando solicitudes concurrentes de manera eficiente y aprovechando bien los recursos del sistema.
• Fácil de extender: El framework permite integrar fácilmente bibliotecas de terceros o agregar funcionalidades personalizadas para necesidades específicas.
• Seguridad: Incluye numerosas características de seguridad integradas, como validación automática de entrada, filtrado de salidas (prevención de XSS), protección CSRF y prevención de inyecciones SQL, ayudando a crear aplicaciones más seguras.
• Sólida comunidad: Cuenta con una comunidad activa de desarrolladores en la que puedes obtener soporte rápido y gran variedad de recursos de terceros.

Gracias a estas ventajas, FuelPHP puede ayudarte a construir aplicaciones web rápidas, seguras y fáciles de mantener, adaptándose tanto a proyectos pequeños como a implementaciones empresariales a gran escala.

Preparar el entorno de desarrollo de FuelPHP con ServBay

ServBay es un entorno local para desarrolladores que ya incluye servicios y herramientas esenciales como PHP, Caddy/Nginx/Apache, MySQL/PostgreSQL/MongoDB, Redis, entre otros. Con ServBay puedes montar fácilmente el entorno necesario para tu proyecto FuelPHP, evitando instalaciones y configuraciones manuales de dependencias.

Esta guía detalla cómo utilizar el entorno PHP, el servidor web (Caddy) y los servicios de base de datos y caché que proporciona ServBay para crear y ejecutar un proyecto FuelPHP. Aprovecharemos la función de Sitios Web de ServBay para configurar el servidor web y permitir el acceso rápido y pruebas recurrentes del proyecto en pocos pasos.

Requisitos previos

Antes de comenzar, asegúrate de contar con los siguientes requisitos:

• ServBay está instalado y funcionando correctamente en tu macOS.
• El entorno PHP de ServBay está habilitado (esto ocurre por defecto).
• Los servicios de base de datos (como MySQL) y caché (como Redis o Memcached) que planeas usar están activos y operando correctamente dentro de ServBay.
• ServBay ya incluye Composer, por lo que no necesitas instalarlo por separado.

Crear un proyecto FuelPHP

Ruta recomendada para tus proyectos

Se recomienda colocar todos los proyectos web en el directorio /Applications/ServBay/www. Esto facilita la gestión y configuración por parte de ServBay. Usaremos esta ruta como ejemplo en la guía.

1. Navega al directorio raíz de sitios

   Abre la aplicación Terminal y cambia al directorio recomendado:

   cd /Applications/ServBay/www

2. Crea el directorio del proyecto

   Crea un directorio nuevo para tu proyecto FuelPHP y accede a él:

   mkdir servbay-fuelphp-app
   cd servbay-fuelphp-app

3. Crea el proyecto FuelPHP con Composer

   Descarga e inicializa el framework FuelPHP usando Composer. El punto . indica que la instalación será en el directorio actual:

   composer create-project fuel/fuel .

   Composer descargará automáticamente FuelPHP y sus dependencias en el directorio servbay-fuelphp-app.

Configuración del servidor web (Utilizando Sitios Web de ServBay)

Para acceder a tu proyecto FuelPHP desde el navegador, debes usar la función Sitios Web de ServBay y configurar un host virtual.

1. Abre la interfaz principal de ServBay.
2. Haz clic en el menú Sitios Web en la barra lateral.
3. Presiona el botón Añadir sitio web en la esquina superior derecha.
4. En la ventana emergente, completa la siguiente información:
   • Nombre: Un nombre descriptivo para tu sitio, por ejemplo My First FuelPHP Dev Site.
   • Dominio: Especifica un dominio local de desarrollo, por ejemplo servbay-fuelphp-test.local. ServBay lo resolverá automáticamente en tu equipo.
   • Tipo de sitio web: Selecciona PHP.
   • Versión PHP: Elige la versión de PHP que prefieras (ejemplo: 8.3).
   • Directorio raíz del sitio web: Debe apuntar al directorio de entrada de FuelPHP: public/index.php. Por lo tanto, coloca como raíz /Applications/ServBay/www/servbay-fuelphp-app/public.
5. Haz clic en Añadir para guardar la configuración.

ServBay actualizará la configuración de Caddy y recargará el servicio, haciendo efectivo el nuevo dominio.

Para detalles más extensos, consulta la documentación de ServBay en Añadir tu primer sitio web.

Configuración de conexiones del proyecto FuelPHP

Un proyecto FuelPHP generalmente necesita configurar la conexión a servicios como base de datos y caché.

Configuración de la base de datos

La configuración se encuentra en el archivo fuel/app/config/development/db.php. Edita este archivo y ajusta la información de conexión según tu entorno. Si usas el servicio MySQL por defecto de ServBay, la configuración puede verse así:

<?php
/**
 * Configuración de la base de datos para desarrollo. Estas se combinan con los valores globales.
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // Asegúrate de que la base de datos fuel_dev existe
            'username' => 'root', // Usuario por defecto en MySQL de ServBay
            'password' => 'root', // Contraseña por defecto (¡solo para desarrollo local!)
        ],
        'identifier' => '`', // MySQL requiere comillas invertidas como identificador
    ],
];

Notas:

• Debes crear manualmente la base de datos fuel_dev usando alguna herramienta de gestión como phpMyAdmin o Adminer. El usuario root de MySQL y la contraseña son root por defecto —úsalo solo para desarrollo.
• 'identifier' => ''` es obligatorio para que FuelPHP cite correctamente nombres de tablas y campos en MySQL.

Configuración de caché (Memcached y Redis)

FuelPHP soporta distintos drivers de caché y su configuración se realiza en fuel/app/config/cache.php. Asegúrate de que los servicios Memcached y/o Redis de ServBay estén activos.

Configuración Memcached (fuel/app/config/cache.php):

Si usas Memcached como caché por defecto:

<?php
return [
    'driver' => 'memcached', // Definir memcached como driver por defecto
    'memcached' => [
        'cache_id' => 'fuel', // ID de caché
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // Dirección local de Memcached
                'port'   => 11211,       // Puerto por defecto de Memcached
                'weight' => 100,
            ],
        ],
        'compression' => false, // Si se activa la compresión
    ],
    // ... Otras configuraciones de drivers de caché
];

Normalmente, la versión de PHP en ServBay ya incluye la extensión Memcached.

Configuración de Redis (fuel/app/config/redis.php):

Si prefieres Redis, configura la conexión en un archivo dedicado redis.php:

<?php
return [
    'default' => [
        'hostname' => '127.0.0.1', // Dirección local de Redis
        'port'     => 6379,        // Puerto por defecto de Redis
        'database' => 0,           // Índice de base de datos de Redis
    ],
    // Puedes definir varias conexiones de Redis si lo necesitas
];

La mayoría de versiones de PHP de ServBay también incluyen la extensión de Redis.

Ejemplo de servicios de base de datos y caché

Para demostrar la integración de FuelPHP con servicios de base de datos y caché, añadiremos algunos ejemplos de código.

Preparar una tabla en la base de datos (con las migraciones de FuelPHP)

FuelPHP ofrece la herramienta Oil para la gestión de migraciones (Migrations), lo que permite versionar los cambios de la estructura de la base de datos.

1. Crear un archivo de migración

   Desde la raíz del proyecto (servbay-fuelphp-app), usa Oil para generar una nueva migración y definir la estructura de la tabla users:

   php oil generate migration create_users_table

   Esto creará un nuevo archivo en fuel/app/migrations cuyo nombre incluye un timestamp.

2. Editar el archivo de migración

   Abre el archivo recién creado (fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php) y edita el método up() para definir la estructura. En down() define la reversión:

   <?php
   namespace Fuel\Migrations;
   
   use Fuel\Core\DBUtil;
   
   class Create_users_table
   {
       public function up()
       {
           // Crea la tabla users
           DBUtil::create_table('users', [
               'id'          => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true],
               'name'        => ['type' => 'varchar', 'constraint' => 100],
               'email'       => ['type' => 'varchar', 'constraint' => 100, 'unique' => true],
           ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // Define clave primaria, índices, motor y charset
       }
   
       public function down()
       {
           // Elimina la tabla users (rollback)
           DBUtil::drop_table('users');
       }
   }

3. Ejecutar las migraciones

   Desde la raíz del proyecto (servbay-fuelphp-app), ejecuta la migración para crear las tablas:

   php oil refine migrate

   Si todo fue bien, la tabla users estará disponible en la base de datos fuel_dev.

Añadir código de controlador de ejemplo

Edita el archivo fuel/app/classes/controller/welcome.php para agregar métodos que demuestren operaciones de base de datos y caché:

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // Añadimos el facade DB
use Fuel\Core\Redis; // Añadimos el facade Redis

class Controller_Welcome extends Controller
{
    // Acción por defecto para la página de inicio
    public function action_index()
    {
        return Response::forge('Hello ServBay!');
    }

    // Acción de ejemplo para Memcached
    public function action_memcached()
    {
        // Intenta obtener el valor desde la caché
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // Si no hay nada en caché, establece el valor
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // Cache por 60 segundos
            $value .= ' (from cache)';
        } else {
            $value .= ' (cached)';
        }

        return Response::forge($value);
    }

    // Acción de ejemplo para Redis
    public function action_redis()
    {
        // Obtener instancia de Redis (por defecto)
        $redis = \Redis_Db::instance(); // En FuelPHP 1.x: Redis_Db::instance()
        // Si hay varias conexiones, usa \Redis_Db::instance('nombre_conexion')

        // Guardar datos en Redis
        $redis->set('servbay_redis_key', 'Hello Redis from ServBay!');

        // Recuperar datos de Redis
        $value = $redis->get('servbay_redis_key');

        return Response::forge($value);
    }

    // Acción de ejemplo para insertar registros MySQL
    public function action_mysql_add()
    {
        try {
            // Insertar un registro en la tabla users
            $result = DB::insert('users')->set([
                'name' => 'ServBay Demo User ' . time(), // Usar timestamp para unicidad
                'email' => 'demo_user_' . time() . '@servbay.test',
            ])->execute(); // execute() devuelve un array con el nuevo ID

            return Response::forge('User added with ID: ' . $result[0]);
        } catch (\Database_Exception $e) {
            // Captura excepciones de DB, como correo duplicado
            return Response::forge('Error adding user: ' . $e->getMessage(), 500);
        }
    }

    // Acción de ejemplo para leer registros MySQL
    public function action_mysql()
    {
        // Obtener todos los usuarios de la tabla
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

        // Devolver la lista de usuarios en formato JSON
        return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
    }
}

Notas:

• Se han importado los facades DB y Redis para uso directo.
• Se utiliza el prefijo servbay_ en las claves de caché para evitar conflictos.
• La acción de inserción de MySQL agrega una marca de tiempo para garantizar unicidad y emplea manejo de errores con mensajes claros.
• En FuelPHP 1.x, accede a la instancia de Redis a través de \Redis_Db::instance().

Configurar las rutas

Para acceder desde el navegador a las nuevas acciones, configura las rutas correspondientes en fuel/app/config/routes.php. Por defecto, FuelPHP ya enruta hacia Controller_Welcome, pero es necesario especificar las nuevas acciones.

Agrega o modifica el arreglo de retorno en fuel/app/config/routes.php:

<?php
return array(
    '_root_'  => 'welcome/index',  // Ruta por defecto para la acción index de welcome
    '_404_'   => 'welcome/404',    // Ruta para error 404

    // Rutas para las acciones de ejemplo
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... Otras rutas
);

Acceder y probar el sitio web

Ya puedes abrir el dominio configurado en ServBay, por ejemplo https://servbay-fuelphp-test.local, para probar tu proyecto FuelPHP y las conexiones de servicios.

• Página principal: https://servbay-fuelphp-test.local
  • Resultado esperado: Hello ServBay!
• Prueba Memcached: https://servbay-fuelphp-test.local/memcached
  • Primer acceso: Hello Memcached from ServBay! (from cache) (si Memcached funciona)
  • Accesos siguientes: Hello Memcached from ServBay! (cached) (si el valor no expira)
• Prueba Redis: https://servbay-fuelphp-test.local/redis
  • Resultado esperado: Hello Redis from ServBay! (si Redis está activo)
• Añadir usuario a MySQL: https://servbay-fuelphp-test.local/mysql_add
  • Resultado esperado: User added with ID: [nuevo ID] (si la BD y tabla existen)
• Leer usuarios de MySQL: https://servbay-fuelphp-test.local/mysql
  • Resultado esperado: Un array JSON de todos los registros de la tabla users

Sobre HTTPS: ServBay configura certificados SSL de forma predeterminada para sitios locales, utilizando ServBay User CA o ServBay Public CA. Si tu navegador marca el certificado como no confiable, asegúrate de haber confiado en el certificado CA de ServBay en tu sistema.

Notas importantes

• Revisa que en la interfaz de ServBay todos los servicios usados (PHP, Caddy/Nginx/Apache, MySQL, Redis, Memcached) estén en estado activo.
• Recuerda crear manualmente la base de datos fuel_dev (o la base que configures en db.php) en la herramienta de gestión de bases de datos de ServBay. Las migraciones solo crean tablas, no la base de datos en sí.
• El archivo de entrada público de FuelPHP es public/index.php, así que la raíz del sitio web debe apuntar al subdirectorio public de tu proyecto en la configuración de Sitio Web de ServBay.

Conclusión

Con ServBay puedes montar un entorno de desarrollo local completo para tus proyectos FuelPHP en macOS de forma sencilla. Esta guía te ha mostrado cómo crear el proyecto, configurar el servidor web con la función Sitios Web, conectar con bases de datos y servicios de caché, y comprobar que todo funciona con ejemplos prácticos. La integración y configuración simplificada que ofrece ServBay aumentará notablemente tu productividad.

¡Esperamos que esta guía te ayude a iniciar tu viaje de desarrollo con FuelPHP en ServBay sin dificultad!