Crear y Ejecutar Proyectos CakePHP con ServBay

ServBay es un entorno de desarrollo web local diseñado para macOS, que integra múltiples lenguajes como PHP, Node.js, Python, Go y Java, así como servicios de base de datos como MySQL, PostgreSQL, MongoDB y Redis, junto a los servidores web Caddy o Nginx. Proporciona una plataforma de desarrollo cómoda y eficiente, permitiendo a los desarrolladores configurar y gestionar fácilmente proyectos locales.

Este artículo te guiará paso a paso para crear, configurar y ejecutar un proyecto CakePHP utilizando ServBay. CakePHP es un popular framework de desarrollo web PHP que sigue el patrón MVC (Modelo-Vista-Controlador), reconocido por su rapidez de desarrollo, potente ORM y avanzadas funcionalidades de seguridad integradas. Aprovechando la facilidad de ServBay, podrás comenzar rápidamente tu desarrollo con CakePHP.

¿Qué es CakePHP?

CakePHP es un framework de desarrollo web PHP de código abierto que proporciona una estructura básica para desarrollar aplicaciones web de forma rápida y estructurada sin sacrificar la flexibilidad. Se basa en el principio de “convención sobre configuración”, simplificando muchas tareas habituales en el desarrollo.

Funcionalidades y Ventajas Principales de CakePHP

• Basado en MVC: Organización clara del código, fácil de mantener y extender.
• Desarrollo rápido: Herramienta de línea de comandos (Bake) para generación automática de código, acelerando el desarrollo.
• Potente ORM (Mapeo Objeto-Relacional): Simplifica la interacción con la base de datos y soporta múltiples sistemas de bases de datos.
• Seguridad integrada: Protección CSRF, prevención contra inyecciones SQL, validación de datos y más.
• Motor de plantillas flexible: Soporte para diferentes tecnologías de capa de vista.
• Comunidad activa y amplio ecosistema de plugins: Fácil acceso a soporte y extensibilidad de funcionalidades.
• Documentación completa: Guías detalladas y referencia de la API.

CakePHP es adecuado para desarrollar aplicaciones web de cualquier escala, desde APIs simples hasta sistemas empresariales complejos.

Configuración del Entorno de Desarrollo CakePHP con ServBay

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

• Intérprete PHP preinstalado con extensiones comunes.
• Gestor de paquetes Composer preinstalado.
• Configuración sencilla de servidor web (Caddy/Nginx).
• Bases de datos integradas (MySQL, PostgreSQL, Redis, etc).

Con ServBay evitas la complejidad de instalar y configurar estos componentes manualmente.

Requisitos Previos

Antes de comenzar, asegúrate de lo siguiente:

1. Instalar ServBay: Descarga e instala ServBay correctamente en tu sistema macOS.
2. Iniciar los servicios de ServBay: Abre la aplicación ServBay y verifica que los paquetes necesarios (por ejemplo, PHP, la base de datos que desees utilizar como MySQL o PostgreSQL, y servicios de caché como Redis o Memcached) estén activos. Los puedes gestionar desde la pestaña “Paquetes” del panel de control de ServBay.
3. Familiarízate con la operación básica de ServBay: Aprende a añadir y configurar sitios web en ServBay. Si eres nuevo, se recomienda leer primero la Guía Básica de Uso de ServBay.

Crear un Proyecto CakePHP

ServBay recomienda mantener tus archivos de proyectos web organizados bajo el directorio /Applications/ServBay/www, para que pueda reconocer y gestionar tus sitios automáticamente.

1. Abrir la terminal

   Inicia la aplicación Terminal en tu Mac.

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

   Cambia al directorio recomendado por ServBay:

   cd /Applications/ServBay/www

3. Crea el directorio para tu proyecto

   Crea una subcarpeta para tu proyecto CakePHP. Usaremos servbay-cakephp-app como ejemplo:

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

4. Crear el proyecto CakePHP con Composer

   ServBay ya incluye Composer. Dentro del directorio del proyecto, ejecuta el siguiente comando para crear el esqueleto de CakePHP:

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

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

5. Instalar el driver ORM (si vas a usar PostgreSQL)

   Si planeas usar PostgreSQL como base de datos, instala el driver ORM adicional:

   composer require cakephp/orm-pgsql

   Para MySQL, normalmente no se requiere instalar un driver adicional ya que viene incluido en las dependencias principales de CakePHP.

Configuración Inicial

Una vez creado el proyecto, realiza la configuración básica, especialmente de la conexión a la base de datos.

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

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

   Ejemplo de configuración de conexión 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 base de datos, por defecto local en ServBay
           //'port' => '3306', // Puerto MySQL por defecto 3306, PostgreSQL por defecto 5432
           'username' => 'root', // Usuario por defecto en ServBay
           'password' => 'password', // Contraseña por defecto en ServBay
           'database' => 'servbay_cakephp_app', // El nombre de la base de datos que crearás
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Set identifier quoting to true if you are using words like "user" as your table name.
            * But if you are using words like "cake" you can set it to false.
            * If you don't know use true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Current limitations include the following:
            * - Most drivers do not support setting isolation levels via PDO options.
            *   Using them will result in an error.
            * - Not all drivers support setting the charset via PDO options.
            *   Using them will result in an error.
            * - PDO options are not supported for packaged drivers like Postgres from CakePHP.
            *   For Postgres, you only need to set the encoding.
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // Si usas la variable de entorno DATABASE_URL, puedes habilitar esta línea
       ],
   ],

   Ajusta el driver y el port según el tipo de base de datos (MySQL o PostgreSQL) que estés usando. Asegúrate de que el nombre de la base de datos coincide con el que vas a crear.

Configura el Servidor Web (Crear un Sitio en ServBay)

Para acceder a tu proyecto CakePHP a través del navegador, debes crear un sitio en ServBay que apunte al directorio de tu proyecto.

1. Abre el panel de control de ServBay

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

2. Navega a la pestaña “Sitios”

   En la barra lateral izquierda del panel, selecciona “Sitios” (antes llamada “Hosts”).

3. Agrega un nuevo sitio web

   Haz clic en el botón + para añadir un nuevo sitio. Rellena la siguiente información:

   • Nombre: Elige un nombre descriptivo, como Mi Sitio Dev CakePHP.
   • Dominio: Asigna un dominio de desarrollo local, por ejemplo servbay-cakephp-test.local. ServBay lo asociará automáticamente a localhost.
   • Tipo de sitio: Selecciona PHP.
   • Versión PHP: Elige una versión compatible con tu CakePHP (CakePHP 4+ requiere PHP 7.4+, CakePHP 5+ requiere PHP 8.1+). Por ejemplo 8.3.
   • Raíz del documento: ¡Importante! La raíz web del proyecto CakePHP no es el directorio principal sino la carpeta webroot dentro de tu proyecto. Usa /Applications/ServBay/www/servbay-cakephp-app/webroot (reemplaza servbay-cakephp-app por el nombre real de tu proyecto).

4. Guarda y aplica los cambios

   Haz clic en “Guardar” en la esquina inferior derecha. ServBay te pedirá aplicar los cambios; confirma y listo. Se configurará el servidor web (Caddy o Nginx) para responder al dominio servbay-cakephp-test.local apuntando al directorio webroot de tu proyecto.

Consulta la sección Agregar el primer sitio en la documentación de ServBay para instrucciones detalladas.

Verifica la Configuración Básica

Ahora deberías poder acceder a tu sitio web desde el navegador.

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

Si todo está bien configurado, verás la página de bienvenida de CakePHP. Esto indica que el entorno PHP, el servidor web y la configuración del sitio en ServBay funcionan correctamente.

Integración con Bases de Datos y Servicios de Caché

CakePHP cuenta con un potente ORM y un sistema de caché unificado, lo que facilita la integración con las bases de datos y servicios de caché que proporciona ServBay.

Ejemplo con Base de Datos Relacional (MySQL / PostgreSQL)

A continuación, veremos cómo usar el ORM de CakePHP para conectar con una base de datos MySQL o PostgreSQL en ServBay, crear una tabla users y realizar operaciones CRUD.

1. Crea la base de datos en ServBay

   Antes de migrar la base de datos, crea una nueva base desde la herramienta de gestión que prefieras (phpMyAdmin para MySQL/MariaDB, pgAdmin para PostgreSQL o herramientas como Navicat/DBeaver). Conéctate a la base de datos (usualmente 127.0.0.1, usuario root, contraseña password) y crea la base llamada servbay_cakephp_app.

2. Crea el archivo Model ORM

   CakePHP requiere un archivo Model para representar cada tabla. Crea UsersTable.php para la tabla users.

   Guarda lo siguiente en src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Si necesitas reglas de validación
   
   class UsersTable extends Table
   {
       /**
        * Initialize method
        *
        * @param array $config The configuration for the Table.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Indica el nombre de la tabla
           $this->setDisplayField('name'); // Campo por defecto para mostrar
           $this->setPrimaryKey('id'); // Define la clave primaria
   
           // Si necesitas comportamiento de timestamps
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Reglas de validación por defecto.
        *
        * @param \Cake\Validation\Validator $validator Validator instance.
        * @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']); // Asegura que el email sea único
   
           return $validator;
       }
   }

3. Crea el archivo de migraciones con la herramienta Bake

   CakePHP recomienda utilizar migraciones para gestionar la estructura de la base de datos. En la raíz de tu proyecto (/Applications/ServBay/www/servbay-cakephp-app), ejecuta Bake para generar la migración de la tabla users:

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

   Este comando crea la migración para una tabla con los campos name (string) y email (string único).

4. Ejecuta la migración de la base de datos

   Aplica la migración con:

   bin/cake migrations migrate

   Si todo va bien, la tabla users aparecerá en tu base de datos.

5. Configura la conexión de la base de datos (si aún no lo hiciste)

   Confirma que la configuración Datasources.default en config/app_local.php coincide con tu base y credenciales.

   • Ejemplo para 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',
             // ... otros ajustes
         ],
     ],

   • Ejemplo para 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 por defecto ServBay
             'password' => 'password', // Contraseña por defecto ServBay
             'database' => 'servbay_cakephp_app',
             // ... otros ajustes
         ],
     ],

6. Agrega rutas de ejemplo y métodos al controlador

   Edita config/routes.php para añadir rutas de ejemplo que agreguen y muestren 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']);
   
       // Rutas de ejemplo 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);
   });

   Modifica src/Controller/PagesController.php para añadir métodos que gestionen la base de datos:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Para manejar errores cuando no se encuentran registros
   
   class PagesController extends AppController
   {
       /**
        * Muestra una vista
        *
        * @param array ...$path Segmentos de la 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 de base de datos: agregar un usuario
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Obtener la instancia de la tabla Users
   
           // Crea una nueva entidad de usuario
           $user = $usersTable->newEntity([
               'name' => 'Usuario Demo ServBay',
               'email' => '[email protected]' // Email de ejemplo con la marca ServBay
           ]);
   
           // Intenta guardar la entidad en la base de datos
           if ($usersTable->save($user)) {
               return new Response(['body' => '¡Usuario agregado exitosamente! ID de usuario: ' . $user->id]);
           } else {
               // Si falla el guardado, probablemente por errores de validación u otros motivos
               $errors = $user->getErrors(); // Recupera mensajes de error de validación
               return new Response(['body' => 'No se pudo agregar el usuario. Errores: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Ejemplo de base de datos: listar todos los usuarios
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users'); // Obtener la instancia de tabla Users
   
           // Busca todos los usuarios
           $users = $usersTable->find()->all();
   
           // Codifica el resultado como JSON
           return new Response(['body' => json_encode($users->toArray())]); // Usa toArray() para convertir la colección en array
       }
   }

7. Accede al ejemplo de base de datos

   Desde tu navegador:

   • Visita https://servbay-cakephp-test.local/db-add-user para agregar un usuario (verás un mensaje de éxito).
   • Visita https://servbay-cakephp-test.local/db-list-users para ver la lista de usuarios (debería incluir el usuario recién creado).

Con estos pasos, tu proyecto CakePHP estará conectado al sistema de base de datos relacional en ServBay y podrás ejecutar operaciones ORM básicas.

Ejemplo de Servicio de Caché (Memcached / Redis)

El API unificada de caché de CakePHP permite alternar fácilmente entre motores como Memcached o Redis. ServBay incluye extensiones PHP y servicios para ambos.

Primero, asegúrate de tener activos los servicios Memcached o Redis desde la pestaña “Paquetes” en el panel de ServBay.

1. Configura la conexión de caché

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

   • Ejemplo con Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'], // Dirección y puerto Memcached por defecto en ServBay
             'prefix' => 'servbay_cakephp_', // Prefijo para las claves
         ],
         // ... otras configuraciones de caché
     ],

   • Ejemplo con Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1', // Dirección Redis por defecto en ServBay
             'port' => 6379, // Puerto por defecto Redis
             'password' => null, // Especifica la contraseña si tu Redis la requiere
             'database' => 0, // Índice de base de datos Redis
             'prefix' => 'servbay_cakephp_', // Prefijo para las claves
         ],
         // ... otras configuraciones de caché
     ],

   Elige la configuración correspondiente según el motor de caché que utilices.

2. Agrega rutas de ejemplo y métodos al controlador

   Edita config/routes.php para añadir rutas de ejemplo para la caché:

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

   Añade en src/Controller/PagesController.php los métodos correspondientes:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache; // Importa la clase Cache
   // ... otros use
   
   class PagesController extends AppController
   {
       // ... otros métodos (display, dbAddUser, dbListUsers)
   
       /**
        * Ejemplo de caché: uso de Memcached
        */
       public function cacheMemcached(): Response
       {
           // Asegúrate que en app_local.php 'default' usa MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey); // Intenta leer de la caché
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Caché vacía
               $responseBody = '¡Fallo de caché! Guardando "¡Hola Memcached!" en caché.';
               $dataToCache = '¡Hola Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Escribe usando la configuración por defecto (Memcached)
           } else {
               // Caché con datos
               $responseBody = '¡Caché encontrada! Dato en caché: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Ejemplo de caché: uso de Redis
        */
       public function cacheRedis(): Response
       {
            // Asegúrate que en app_local.php 'default' usa RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey); // Intenta leer de la caché
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Caché vacía
               $responseBody = '¡Fallo de caché! Guardando "¡Hola Redis!" en caché.';
               $dataToCache = '¡Hola Redis!';
               Cache::write($cacheKey, $dataToCache, 'default'); // Escribe usando la configuración por defecto (Redis)
           } else {
               // Caché con datos
               $responseBody = '¡Caché encontrada! Dato en caché: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Accede a los ejemplos de caché

   En el navegador:

   • Si configuraste Memcached, visita https://servbay-cakephp-test.local/cache-memcached. La primera vez verá “Fallo de caché”, al refrescar mostrará “Caché encontrada”.
   • Si configuraste Redis, visita https://servbay-cakephp-test.local/cache-redis. Se comportará igual.

Con esto, tu proyecto CakePHP podrá trabajar con los sistemas de caché provistos por ServBay.

Consideraciones

• Credenciales de base de datos: Las credenciales por defecto de ServBay (root/password) son solo para desarrollo local. Usa contraseñas más seguras en producción.
• Raíz del sitio: Siempre apunta la “raíz del documento” del sitio en ServBay a la carpeta webroot del proyecto CakePHP, y no al directorio principal. Es la práctica recomendada para CakePHP.
• Compatibilidad PHP: Verifica que la versión de PHP elegida en ServBay sea compatible con tu versión de CakePHP. Consulta la documentación oficial de CakePHP para los requisitos de versiones.
• Puertos de ServBay: Si otros programas usan los puertos 80 o 443, cambia la configuración de puertos en ServBay y ajusta tu archivo hosts o usa el puerto específico en la URL.

Preguntas Frecuentes (FAQ)

• P: ¿Al acceder a servbay-cakephp-test.local aparece el error “Página no encontrada”?
  • R: Verifica que la “raíz del documento” en ServBay apunte a /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Asegúrate de que el servidor web (Caddy/Nginx) en ServBay esté en ejecución.
  • Comprueba que el archivo hosts apunte servbay-cakephp-test.local a 127.0.0.1 (ServBay lo gestiona automáticamente, pero conviene revisar).
  • Revisa el archivo .htaccess de CakePHP o la configuración del servidor web (webroot/.htaccess suele estar bien por defecto).
• P: ¿Fallo de conexión con la base de datos?
  • R: Asegura que el servicio de base de datos correspondiente (MySQL/PostgreSQL) está activo en ServBay.
  • Revisa la configuración en config/app_local.php (host, puerto, usuario, contraseña y base de datos) y que coincida con los datos de ServBay.
  • Asegura que la base de datos servbay_cakephp_app existe.
• P: ¿No puedes ejecutar comandos Composer (bin/cake)?
  • R: Confirma estar ubicado en la raíz del proyecto (/Applications/ServBay/www/servbay-cakephp-app) en la terminal.
  • Asegura que los paquetes PHP y Composer están activos en ServBay.
  • Comprueba que el comando php sea reconocible (ServBay normalmente añade PHP al PATH; en caso contrario, usa la terminal integrada de ServBay o ajusta el PATH manualmente).

Resumen

Con ServBay puedes crear un entorno de desarrollo local para CakePHP en macOS de forma eficiente. La integración previa de PHP, Composer, el servidor web y los servicios de base de datos simplifica enormemente la configuración. Este tutorial cubre todo el flujo, desde la creación y configuración básica del proyecto, el ajuste del servidor web, hasta la integración con bases de datos relacionales y sistemas de caché, ayudándote a iniciar rápidamente tu desarrollo con CakePHP. Aprovecha la comodidad de ServBay y enfócate en escribir código, no en la configuración del entorno.