Crear y Ejecutar un Proyecto CakePHP con ServBay

ServBay es un entorno de desarrollo local para web compatible con macOS y Windows, que integra múltiples lenguajes como PHP, Node.js, Python, Go, Java y servicios de bases de datos como MySQL, PostgreSQL, MongoDB y Redis, además de servidores web como Caddy o Nginx. Ofrece una plataforma eficiente y sencilla que facilita la gestión y creación de proyectos locales para desarrolladores.

Este artículo te guiará para crear, configurar y ejecutar un proyecto CakePHP utilizando ServBay. CakePHP es un framework popular de desarrollo web en PHP, basado en el patrón MVC (Modelo-Vista-Controlador), conocido por su rapidez en desarrollo, potente ORM y características de seguridad integradas. Combinando la facilidad de ServBay, puedes empezar a desarrollar con CakePHP rápidamente.

¿Qué es CakePHP?

CakePHP es un framework de código abierto para desarrollo de aplicaciones web en PHP, que proporciona una infraestructura sólida para desarrollar aplicaciones web de manera rápida y estructurada, sin perder flexibilidad. Se basa en el principio de “convención sobre configuración”, simplificando muchas tareas habituales de desarrollo.

Principales Características y Ventajas de CakePHP

• Basado en el patrón MVC: Estructura clara del código, fácil de mantener y escalar.
• Desarrollo rápido: Cuenta con herramientas CLI (Bake) que generan código y aceleran el proceso.
• Potente ORM (Mapeo objeto-relacional): Simplifica la interacción con base de datos, soportando varios sistemas.
• Seguridad integrada: Incluye protección CSRF, contra inyección SQL, validación de entradas, entre otras.
• Motor de plantillas flexible: Compatible con distintas tecnologías de vistas.
• Comunidad activa y gran variedad de plugins: Fácil encontrar soporte y ampliar funcionalidades.
• Documentación completa: Guías detalladas y referencia de API.

CakePHP es ideal para construir aplicaciones web de cualquier tamaño, desde APIs simples hasta sistemas empresariales complejos.

Configurar el Entorno de Desarrollo CakePHP con ServBay

ServBay proporciona un entorno integrado ideal para desarrollo con CakePHP, incluyendo:

• PHP y sus extensiones preinstaladas.
• Composer ya instalado.
• Servidor web configurable (Caddy/Nginx).
• Servicios de bases de datos integrados (MySQL, PostgreSQL, Redis, entre otros).

Con ServBay, evitas los tediosos procesos de instalación y configuración manual de estos componentes.

Requisitos previos

Antes de empezar, asegúrate de lo siguiente:

1. ServBay instalado: Descarga e instala ServBay en macOS.
2. Servicios de ServBay activos: Inicia la aplicación ServBay y comprueba que los paquetes requeridos (PHP, base de datos como MySQL o PostgreSQL, y servicios de caché como Redis o Memcached) estén corriendo. En la pestaña “Paquetes” del panel de control de ServBay puedes gestionar estos servicios.
3. Familiaridad básica con ServBay: Aprende a agregar y configurar sitios. Si es tu primera vez, revisa antes la Guía básica de uso de ServBay.

Crear un Proyecto CakePHP

ServBay recomienda almacenar tus archivos de proyectos web en el directorio /Applications/ServBay/www, facilitando el reconocimiento y gestión automática de sitios por ServBay.

1. Abre la terminal

   Lanza la aplicación de Terminal en macOS.

2. Navega al directorio raíz de sitios de ServBay

   Cambia al directorio recomendado para sitios en ServBay:

   cd /Applications/ServBay/www

3. Crea un directorio de proyecto

   Crea un subdirectorio para tu proyecto CakePHP. Usaremos servbay-cakephp-app como nombre de ejemplo:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Crear el proyecto CakePHP con Composer

   Composer ya está preinstalado en ServBay. Ejecuta el siguiente comando en el directorio del proyecto para crear la estructura base de CakePHP:

   composer create-project --prefer-dist cakephp/app .

   Este comando descargará la última versión estable de CakePHP y sus dependencias en el directorio actual (.).

5. Instalar driver ORM (si usas PostgreSQL)

   Si planeas usar PostgreSQL, instala el driver adicional:

   composer require cakephp/orm-pgsql

   Si usas MySQL no es necesario instalar drivers extra, ya vienen incluidos con CakePHP.

Configuración Inicial

Después de crear el proyecto, realiza las configuraciones básicas, especialmente los datos de conexión a la base de datos.

1. Configurar variables de entorno y conexión a la base de datos

   La configuración local en CakePHP se realiza principalmente en el archivo config/app_local.php. Edita este archivo, busca la sección Datasources, y ajusta los datos de conexión. Por defecto, el usuario de la base de datos en ServBay es root y la contraseña es password.

   Ejemplo de configuración para MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // O \Cake\Database\Driver\Postgres::class para PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // Dirección del servidor de la base de datos (local en ServBay)
           //'port' => '3306', // Puerto por defecto MySQL 3306, PostgreSQL 5432
           'username' => 'root', // Usuario por defecto ServBay
           'password' => 'password', // Contraseña por defecto ServBay
           'database' => 'servbay_cakephp_app', // Nombre de la base de datos a crear
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Establece quoteIdentifiers a true si usas palabras reservadas como nombre de tabla ("user").
            * Si usas nombres como "cake", puede estar en false.
            * Si no estás seguro, usa true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Limitaciones actuales:
            * - La mayoría de drivers no soportan niveles de aislamiento vía opciones PDO.
            *   Usarlas puede ocasionar errores.
            * - No todos los drivers soportan configuración de charset vía PDO.
            *   Usarlas puede ocasionar errores.
            * - Las opciones PDO no son compatibles con drivers empaquetados como Postgres en CakePHP.
            *   Para Postgres, sólo necesitas establecer el encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Si usas la variable de entorno DATABASE_URL, activa esta línea
       ],
   ],

   Ajusta el driver y el posible port según el tipo de base de datos. Asegúrate que el nombre de la base de datos corresponde al que vas a crear.

Configurar el servidor web (creando sitio en ServBay)

Para acceder al proyecto CakePHP desde el navegador, necesitas configurar un sitio en ServBay apuntando al directorio del proyecto.

1. Abre el panel de control de ServBay

   Haz clic en el icono de ServBay para abrir el panel.

2. Ve a la pestaña “Sitios”

   En el panel, selecciona “Sitios” en la barra lateral izquierda (anteriormente “Hosts”).

3. Agrega un nuevo sitio

   Pulsa el botón + para agregar un sitio nuevo. Completa la información:

   • Nombre: Un nombre identificativo, ejemplo Mi sitio CakePHP Dev.
   • Dominio: Un dominio local, como servbay-cakephp-test.local. ServBay lo asociará automáticamente al equipo local.
   • Tipo de sitio: Selecciona PHP.
   • Versión de PHP: Elige la versión que requiera tu CakePHP (CakePHP 4+ requiere PHP 7.4+, CakePHP 5+ pide PHP 8.1+), por ejemplo 8.3.
   • Directorio raíz: ¡Importante! El directorio raíz para el servidor web debe ser el subdirectorio webroot del proyecto CakePHP, no el principal. Establece /Applications/ServBay/www/servbay-cakephp-app/webroot (reemplaza servbay-cakephp-app por el nombre real de tu proyecto).

4. Guarda y aplica los cambios

   Al terminar, haz clic en “Guardar”. ServBay pedirá aplicar cambios; confirma. ServBay configurará automáticamente el servidor web (Caddy o Nginx) para responder al dominio servbay-cakephp-test.local y apuntar al webroot de tu proyecto.

Para una guía detallada, revisa la sección Agregar el primer sitio en la documentación de ServBay.

Verificar la configuración básica

Ahora deberías poder acceder al sitio desde el navegador.

Abre el navegador y visita el dominio configurado, por ejemplo https://servbay-cakephp-test.local.

Si todo está correcto, verás la página de bienvenida predeterminada de CakePHP, lo que indica que PHP, el servidor web y la configuración de ServBay funcionan bien.

Integración de servicios de base de datos y caché

CakePHP cuenta con un potente ORM y una capa de caché que facilita la integración con bases de datos y servicios de caché en ServBay.

Ejemplo de base de datos relacional (MySQL / PostgreSQL)

Este ejemplo muestra cómo usar el ORM de CakePHP con una base de datos MySQL o PostgreSQL en ServBay, creando la tabla users y realizando operaciones CRUD.

1. Crear base de datos en ServBay

   Antes de migraciones, crea una base de datos nueva usando el administrador de bases de datos incluido en ServBay (phpMyAdmin para MySQL/MariaDB, pgAdmin para PostgreSQL, o herramientas como Navicat/DBeaver). Conéctate usando la IP 127.0.0.1, usuario root y contraseña password, luego crea la base servbay_cakephp_app.

2. Crear archivo Model ORM

   El ORM necesita un archivo Model para cada tabla. Crea UsersTable.php para la tabla users.

   Guarda el siguiente código en src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Para reglas de validación
   
   class UsersTable extends Table
   {
       /**
        * Método de inicialización
        *
        * @param array $config Configuración para la tabla.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Asigna el nombre de la tabla
           $this->setDisplayField('name'); // Campo mostrado por defecto en asociaciones
           $this->setPrimaryKey('id'); // Asigna el campo de clave primaria
   
           // Si necesitas comportamiento autotiempo
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Reglas de validación por defecto.
        *
        * @param \Cake\Validation\Validator $validator Instancia de validador.
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // Verifica unicidad de email
   
           return $validator;
       }
   }

3. Crear archivo de migración con herramienta Bake

   CakePHP recomienda gestionar la estructura de la base de datos mediante migraciones. En la raíz del proyecto (/Applications/ServBay/www/servbay-cakephp-app), ejecuta el siguiente comando para crear la migración y definir la tabla:

   bin/cake bake migration CreateUsers name:string email:string:unique

   Este comando crea un archivo de migración que define la tabla users con los campos name (string) y email (string, único).

4. Aplicar la migración a la base de datos

   Ejecuta el comando de migración para crear la tabla en la base de datos creada:

   bin/cake migrations migrate

   Si es exitoso, la tabla users estará disponible en la base.

5. Configuración de datos de conexión (si no lo hiciste antes)

   Verifica que la configuración de config/app_local.php en Datasources.default corresponda a tu base y credenciales.

   • Ejemplo MySQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // ... otras configuraciones
         ],
     ],

   • Ejemplo PostgreSQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // Puerto por defecto
             'username' => 'root', // Usuario ServBay
             'password' => 'password', // Contraseña ServBay
             'database' => 'servbay_cakephp_app',
             // ... otras opciones
         ],
     ],

6. Agregar rutas y métodos en el controlador de ejemplo

   Modifica config/routes.php para agregar rutas para añadir y listar usuarios:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... otras rutas
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Ejemplo de rutas para base de datos
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... otras rutas
       $routes->fallbacks(DashedRoute::class);
   });

   Edita src/Controller/PagesController.php para agregar métodos que realicen operaciones en la base:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Para manejar excepciones de no encontrado
   
   class PagesController extends AppController
   {
       /**
        * Mostrar una vista
        *
        * @param array ...$path Segmentos de ruta.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... método display por defecto
           return new Response(['body' => '¡Hola ServBay! Esta es la página por defecto.']);
       }
   
       /**
        * Ejemplo base de datos: agregar usuario
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Obtiene instancia de Users Table
   
           // Crea una entidad de usuario nueva
           $user = $usersTable->newEntity([
               'name' => 'Usuario Demo ServBay',
               'email' => 'servbay-demo@servbay.test' // Ejemplo de email con marca ServBay
           ]);
   
           // Intenta guardar en la base de datos
           if ($usersTable->save($user)) {
               return new Response(['body' => '¡Usuario agregado exitosamente! ID de usuario: ' . $user->id]);
           } else {
               // Si falla, puede deberse a errores de validación u otros problemas
               $errors = $user->getErrors(); // Obtiene errores de validación
               return new Response(['body' => 'No fue posible agregar el usuario. Errores: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Ejemplo base de datos: listar todos los usuarios
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Instancia de Users Table
   
           // Busca todos los usuarios
           $users = $usersTable->find()->all();
   
           // Devuelve resultados como JSON
           return new Response(['body' => json_encode($users->toArray())]); // Convierte la colección a array y lo muestra
       }
   }

7. Probar el ejemplo de base de datos

   Abre el navegador:

   • Visita https://servbay-cakephp-test.local/db-add-user para añadir un usuario. Debes ver el mensaje de éxito.
   • Visita https://servbay-cakephp-test.local/db-list-users para visualizar la lista de usuarios en la base.

Siguiendo estos pasos, tu proyecto CakePHP estará conectado a la base de datos relacional en ServBay y podrás realizar operaciones ORM básicas.

Ejemplo de servicios de caché (Memcached / Redis)

CakePHP ofrece una API de caché unificada y permite cambiar el motor entre Memcached y Redis fácilmente. ServBay viene con las extensiones PHP de Memcached y Redis instaladas, y los servicios funcionales.

Primero, asegúrate de que, en la pestaña “Paquetes” del panel de ServBay, los servicios de Memcached o Redis estén encendidos.

1. Configurar la conexión de caché

   Edita el archivo config/app_local.php y ajusta la sección Cache.

   • Ejemplo Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // IP y puerto por defecto de Memcached en ServBay
             'prefix' => 'servbay_cakephp_', // Prefijo para los keys
         ],
         // ... otras configuraciones
     ],

   • Ejemplo Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // IP por defecto de Redis en ServBay
             'port' => 6379, // Puerto por defecto Redis
             'password' => null, // Si Redis tiene contraseña, colócala aquí
             'database' => 0, // Índice de base en Redis
             'prefix' => 'servbay_cakephp_', // Prefijo de keys
         ],
         // ... otras configuraciones
     ],

   Elige la configuración de acuerdo al servicio que uses.

2. Agregar rutas y métodos en el controlador de caché

   Edita config/routes.php para agregar rutas de ejemplo de caché:

   // config/routes.php
   // ... otras rutas
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... otras rutas

   Modifica src/Controller/PagesController.php y crea métodos de prueba para caché:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache; // Importa la clase Cache
   // ... otras importaciones
   
   class PagesController extends AppController
   {
       // ... otros métodos (display, dbAddUser, dbListUsers)
   
       /**
        * Ejemplo de caché: usando Memcached
        */
       public function cacheMemcached(): Response
       {
           // Verifica que 'default' en app_local.php tenga MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey); // Intenta leer de caché
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Fallo en caché
               $responseBody = '¡Cache miss! Escribiendo "Hello Memcached!" en caché.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Escribe en la configuración 'default' (Memcached)
           } else {
               // Cache hit
               $responseBody = '¡Cache hit! Datos de caché: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Ejemplo de caché: usando Redis
        */
       public function cacheRedis(): Response
       {
            // Verifica que 'default' en app_local.php tenga RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey); // Intenta leer de caché
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Fallo en caché
               $responseBody = '¡Cache miss! Escribiendo "Hello Redis!" en caché.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Escribe en la configuración 'default' (Redis)
           } else {
               // Cache hit
               $responseBody = '¡Cache hit! Datos de caché: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Probar el ejemplo de caché

   Abre el navegador:

   • Si usas Memcached, visita https://servbay-cakephp-test.local/cache-memcached. La primer vez muestra “Cache miss”, al refrescar muestra “Cache hit”.
   • Si usas Redis, visita https://servbay-cakephp-test.local/cache-redis. El comportamiento es igual.

¡Tu proyecto CakePHP ya está integrado y usa servicios de caché proveídos por ServBay!

Consideraciones importantes

• Credenciales de base de datos: Los valores predeterminados (root/password) son sólo para desarrollo local. En producción, usa datos más seguros.
• Directorio raíz del sitio: El sitio en ServBay debe apuntar al subdirectorio webroot del proyecto CakePHP, no al directorio principal.
• Compatibilidad de PHP: Revisa que la versión PHP seleccionada en ServBay sea compatible con tu versión de CakePHP. Consulta la documentación oficial.
• Puertos ServBay: Si los puertos predeterminados (80 y 443) están ocupados, modifica la configuración en ServBay y accede usando el puerto asignado o edita el archivo hosts.

Preguntas Frecuentes (FAQ)

• P: ¿Por qué aparece el error “Página no encontrada” al entrar a servbay-cakephp-test.local?
  • R: Revisa que la raíz del sitio apunte a /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Verifica que el servidor web (Caddy/Nginx) esté corriendo.
  • Asegúrate de que el archivo hosts asocie servbay-cakephp-test.local con 127.0.0.1 (ServBay lo gestiona automáticamente, pero puede requerirse revisión).
  • Revisa si los archivos .htaccess o la configuración del servidor web están correctos (usualmente webroot/.htaccess funciona de fábrica).
• P: ¿Falla la conexión con la base de datos?
  • R: Comprueba que los servicios de base de datos (MySQL/PostgreSQL) estén activos en ServBay.
  • Confirma los datos de conexión en config/app_local.php (host, puerto, usuario, contraseña, base de datos).
  • Asegúrate de que hayas creado la base servbay_cakephp_app.
• P: ¿No se ejecuta el comando Composer (bin/cake)?
  • R: Asegúrate de estar en el directorio raíz del proyecto (/Applications/ServBay/www/servbay-cakephp-app) en la terminal.
  • Revisa que PHP y Composer estén activados en ServBay.
  • Verifica que la terminal reconozca el comando php (ServBay lo añade al PATH normalmente). Usa la terminal que incluye ServBay o ajusta el PATH manualmente.

Resumen

Con ServBay puedes crear entornos de desarrollo local para CakePHP de manera eficiente. La integración previa de PHP, Composer, servidores web y servicios de base simplifica la configuración. Este artículo describe el proceso completo: desde la creación del proyecto, la configuración básica y del servidor web, hasta la integración con bases de datos relacionales y servicios de caché, ayudándote a iniciar rápido tu desarrollo con CakePHP. Gracias a la comodidad de ServBay, puedes centrarte en programar sin preocuparte por la complejidad de la configuración del entorno.