Crear y ejecutar un proyecto Phalcon

¿Qué es Phalcon?

Phalcon es un framework PHP de alto rendimiento y código abierto, implementado como una extensión en C. Gracias a esta implementación única, Phalcon ofrece un consumo de recursos extremadamente bajo y una velocidad de ejecución sobresaliente, superando significativamente a la mayoría de los frameworks PHP tradicionales. Siguiendo el patrón arquitectónico MVC (Modelo-Vista-Controlador), Phalcon proporciona una amplia gama de componentes como ORM (Mapeo Objeto-Relacional), motor de plantillas, enrutamiento, caché, gestor de eventos y más, diseñados para ayudar a los desarrolladores a construir rápidamente aplicaciones web y APIs potentes y de alto rendimiento.

Principales características y ventajas de Phalcon

• Rendimiento excepcional: Al ejecutarse como una extensión en C, Phalcon evita la sobrecarga del procesamiento e interpretación de scripts PHP, ofreciendo rendimiento a nivel nativo.
• Eficiencia de recursos: Consumo de memoria muy bajo; ideal para aplicaciones que demandan alto rendimiento y escalabilidad.
• Funcionalidad completa: Incorpora la mayoría de los componentes esenciales para el desarrollo web, reduciendo la dependencia de librerías de terceros.
• Facilidad de uso: API clara y consistente, con documentación detallada, ideal incluso para quienes recién comienzan con Phalcon.
• Alto desacoplamiento: Cada componente está diseñado de manera independiente, permitiendo al desarrollador elegir o reemplazar solo los que necesite.
• Seguridad: Incluye múltiples componentes relacionados con la seguridad, como filtrado de entradas y protección CSRF.

Phalcon es la elección ideal para desarrollar aplicaciones web y APIs de alto rendimiento y escalabilidad, especialmente en proyectos donde la velocidad y la eficiencia en recursos son prioritarios.

Crear y ejecutar un proyecto Phalcon con ServBay

ServBay es un entorno local de desarrollo web diseñado específicamente para macOS. Integra múltiples versiones de PHP, bases de datos (como MySQL, PostgreSQL, MongoDB y Redis), servidores web (Caddy, Nginx, Apache) y otras herramientas para desarrolladores. Con ServBay puedes crear y gestionar fácilmente el entorno necesario para tus proyectos Phalcon.

Esta guía te acompañará para crear un proyecto básico con Phalcon usando el entorno PHP de ServBay, configura el servidor web para su acceso y te muestra cómo integrar bases de datos relacionales (MySQL) y NoSQL (Redis).

Requisitos previos

Antes de empezar, asegúrate de cumplir con los siguientes requisitos:

1. ServBay instalado y en ejecución: Debes haber instalado y arrancado ServBay correctamente en macOS.
2. Versión requerida de PHP habilitada: En ServBay, asegúrate de que la versión de PHP que planeas usar está habilitada.
3. Módulo Phalcon activado: ServBay incluye el módulo Phalcon, pero puede que no esté habilitado por defecto. Actívalo según los pasos indicados en la documentación Cómo habilitar el módulo Phalcon de ServBay para la versión de PHP correspondiente, y reinicia el servicio PHP.
4. Composer disponible: ServBay incluye Composer integrado, por lo que no necesitas instalarlo manualmente. Verifica que puedes ejecutar el comando composer directamente en la terminal.

Versiones de Phalcon y DevTools

El framework Phalcon y sus herramientas de desarrollo (Phalcon DevTools) deben ser compatibles con la versión de PHP que utilices. La siguiente tabla muestra la relación recomendada entre las versiones comunes de PHP, Phalcon y DevTools:

Versión PHP	Versión recomendada de Phalcon	Versión recomendada de Phalcon DevTools	Notas
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1 (o 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (oficial)	DevTools oficial puede tener problemas de compatibilidad en PHP 8.x
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repositorio corregido)	Se recomienda usar una versión corregida mantenida por la comunidad

Importante: Para PHP 8.x y superiores, es posible que Phalcon DevTools oficial no sea totalmente compatible. Se recomienda utilizar la versión corregida de la comunidad. Los pasos para crear el proyecto a continuación incluyen la manera de instalar el DevTools corregido mediante Composer.

Crear un proyecto Phalcon

Ruta recomendada para proyectos

Para facilitar la organización, ServBay recomienda almacenar todos los proyectos web en el directorio raíz predeterminado /Applications/ServBay/www. En este ejemplo usaremos esa carpeta para crear el proyecto.

1. Accede a la carpeta raíz de proyectos y crea tu directorio de proyecto

   Abre la terminal, navega al directorio raíz de ServBay y crea una nueva carpeta para tu proyecto Phalcon (por ejemplo, servbay-phalcon-app):

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. Instala Phalcon DevTools

   Phalcon DevTools es un conjunto de herramientas de línea de comandos que facilita la generación de código, creación de esqueletos de proyectos y gestión de migraciones, entre otros. Instálalo con Composer según tu versión de PHP:

   • Para PHP 5.6, 7.0, 7.1 (Phalcon DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • Para PHP 7.2, 7.3, 7.4 (Phalcon DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • Para PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools versión corregida dev-master): Ya que el DevTools oficial podría presentar incompatibilidades con PHP 8.x, hay que usar la versión corregida de la comunidad. Primero, en el directorio raíz del proyecto (/Applications/ServBay/www/servbay-phalcon-app), crea o edita el archivo composer.json y agrega el repositorio de la versión corregida:

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     Ahora ejecuta el comando de actualización de Composer para instalar DevTools:

     composer update

   Composer creará la carpeta vendor en el directorio raíz de tu proyecto (servbay-phalcon-app). El ejecutable de DevTools se encontrará en vendor/bin/phalcon.

3. Genera la estructura básica del proyecto con Phalcon DevTools

   Usa el comando recién instalado de DevTools para generar la estructura básica de tu proyecto Phalcon. El código del proyecto se ubicará en un subdirectorio (usualmente con el mismo nombre, configuración predeterminada de DevTools):

   vendor/bin/phalcon project servbay-phalcon-app

   Este comando creará un subdirectorio /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app con la estructura inicial del proyecto.

4. Entra al directorio del proyecto

   Cambia al nuevo directorio generado para continuar trabajando desde allí:

   cd servbay-phalcon-app

   Ahora deberías estar en /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configura el entorno del proyecto

La configuración principal de un proyecto Phalcon suele estar en el archivo app/config/config.php. Aquí defines los datos de conexión a la base de datos y otras configuraciones importantes.

1. Edita el archivo de configuración

   Abre /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php en el editor de tu preferencia. Busca o agrega la sección de la base de datos. El usuario predeterminado de MySQL/MariaDB en ServBay es root, sin contraseña, pero por seguridad ServBay recomienda configurar una contraseña robusta. Usamos password como ejemplo; cámbialo según tu configuración real. El nombre de base de datos servbay_phalcon_app se usa como ejemplo (puedes crearlo manualmente si es necesario).

   return new \Phalcon\Config([
       // ... Otras configuraciones ...
       'database' => [
           'adapter' => 'Mysql', // O 'Postgres', etc.
           'host' => '127.0.0.1',
           'username' => 'root', // Usuario por defecto en ServBay
           'password' => 'password', // <-- Cambia por la contraseña de tu BD
           'dbname' => 'servbay_phalcon_app', // <-- Cambia por tu nombre de BD
       ],
       // ... Otras configuraciones ...
   ]);

   Importante: Verifica que el servicio de base de datos (MySQL o MariaDB) está activo en ServBay y que los credenciales concuerdan con esta configuración. También necesitas crear la base de datos servbay_phalcon_app, lo cual puedes hacer desde herramientas de gestión como phpMyAdmin o Adminer incluidas en ServBay.

Configuración del servidor web (usando la función Sitios de ServBay)

Para acceder a tu proyecto Phalcon desde el navegador, debes configurar un host virtual en la funcionalidad Sitios de ServBay, apuntando al directorio público (public) del proyecto.

1. Abre la aplicación ServBay
2. Entra en la configuración de “Sitios”: Haz clic en la opción “Sitios” desde la interfaz principal de ServBay.
3. Agrega un nuevo sitio: Pulsa el botón para añadir un sitio.
   • Nombre: Usa un nombre descriptivo, como Mi Primer Sitio Phalcon.
   • Dominio: Define el dominio local para el sitio, por ejemplo, servbay-phalcon-test.local. ServBay resolverá automáticamente dominios .local en tu equipo.
   • Tipo de sitio: Selecciona PHP.
   • Versión PHP: Escoge la versión correspondiente que tenga el módulo Phalcon habilitado.
   • Directorio raíz del sitio: Este paso es clave. El archivo de entrada index.php de Phalcon está en el directorio public, así que indica como raíz: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Guarda la configuración: ServBay aplicará los cambios automáticamente, y puede requerir reiniciar el servidor web (Caddy o Nginx).

Consulta la guía Agregar el primer sitio web para ver estos pasos detallados. Después de guardar, ServBay gestionará tanto la resolución del dominio local como la configuración del servidor web.

Añade código de ejemplo

Agregamos algo de código simple para comprobar que el proyecto funciona correctamente.

1. Configura las rutas

   Edita el archivo /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php y añade una regla sencilla para la ruta /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Define la ruta por defecto, asignando '/' a IndexController@indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Puedes agregar otras rutas ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crea un controlador

   Edita o crea /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php con el siguiente método indexAction:

   <?php
   namespace App\Controllers; // Asegúrate de que el espacio de nombres es correcto
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Gestiona las peticiones a la ruta raíz '/'
       public function indexAction()
       {
           // Retorna solamente una cadena simple como respuesta
           return 'Hello ServBay!';
       }
   }

Accede al sitio web

Guarda todos los archivos y asegúrate de que ServBay está funcionando. Abre el navegador y entra al dominio que configuraste en ServBay:

https://servbay-phalcon-test.local

Si todo está en orden, deberías ver el mensaje Hello ServBay! en tu navegador.

Integración con bases de datos

Phalcon provee una potente capa de abstracción de bases de datos y ORM. Aprovechando que ServBay integra varios sistemas, puedes enlazarlos fácilmente a tu aplicación Phalcon. Veremos ejemplos con MySQL y Redis.

Base de datos relacional: MySQL

A continuación, mostramos cómo conectar Phalcon a MySQL en ServBay y realizar operaciones de inserción y consulta.

1. Crea la estructura de la base de datos (utilizando migraciones)

   Phalcon DevTools soporta migraciones de base de datos como método estándar para el control de versiones en los esquemas.

   • Genera el archivo de migración: En el directorio del proyecto, ejecuta:

     vendor/bin/phalcon migration generate

     Esto creará un archivo de migración en la carpeta migrations con un nombre tipo YYYYMMDDHHMMSS_MigrationName.php.

   • Edita el archivo de migración: Abre el archivo recién creado y define una tabla simple users en el método morph:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // El nombre de la clase debe coincidir con el del archivo
     {
         /**
          * Ejecuta la migración
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Revertir la migración
          *
          * @return void
          */
         public function down()
         {
             // Opcional: Lógica para revertir cambios, por ejemplo eliminar la tabla
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: El nombre de la clase (UsersMigration_100) debe coincidir con el del archivo, normalmente compuesto de un timestamp y el nombre de la migración.

   • Ejecuta la migración: En el directorio del proyecto, ejecuta para crear la tabla users:

     vendor/bin/phalcon migration run

     Si hay errores de conexión, revisa la configuración de base de datos en app/config/config.php y que el servicio MySQL/MariaDB esté activo en ServBay.

2. Configura la conexión a la base de datos (ya hecho previamente)

   Asegúrate de que la sección 'database' de app/config/config.php apunte al servicio MySQL/MariaDB de ServBay (host por defecto 127.0.0.1, puerto 3306, usuario root, contraseña según configuración).

3. Agrega rutas de ejemplo

   Edita app/config/routes.php agregando rutas para insertar y consultar usuarios:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Ruta para insertar un usuario
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Ruta para listar usuarios
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implementa operaciones de base de datos en el controlador

   Completa el archivo app/controllers/IndexController.php añadiendo los métodos para insertar y consultar usuarios utilizando el adaptador de base de datos de Phalcon:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Adaptador MySQL
   use Phalcon\Db\Enum; // Constantes para modos de fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Ejemplo: insertar usuario
       public function mysqlAddAction()
       {
           // Conexión a la base de datos (preferible usar DI en un proyecto real)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Cambia por tu contraseña real
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Inserta usuario de ejemplo
           $success = $connection->insert(
               'users', // tabla
               ['ServBay Demo User', 'demo@servbay.test'], // valores
               ['name', 'email'] // columnas
           );
   
           // Muestra resultado
           echo $success ? 'Usuario añadido correctamente.' : 'Fallo al añadir usuario.';
       }
   
       // Ejemplo: listar usuarios
       public function mysqlAction()
       {
           // Conexión a la base de datos
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Cambia por tu contraseña real
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Consulta todos los usuarios
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Devuelve en formato JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Nota: En proyectos reales, se recomienda gestionar la conexión a la base de datos como un servicio en el contenedor de dependencia y reutilizar la conexión.

5. Accede a los ejemplos

   • Abre el navegador y accede a https://servbay-phalcon-test.local/mysql-add. Si todo fue bien, verás "Usuario añadido correctamente."
   • Luego entra a https://servbay-phalcon-test.local/mysql. Verás el contenido de la tabla users en JSON, incluyendo el registro añadido.

Base de datos NoSQL: Redis

Veamos cómo conectar y utilizar Redis (que ServBay provee) como sistema de caché en un proyecto Phalcon.

1. Instala la extensión de Redis

   ServBay ya incluye la extensión de Redis en sus paquetes PHP más comunes. Solo asegúrate de que la extensión Redis esté habilitada en la versión de PHP seleccionada.

2. Configura la conexión a Redis

   Añade la configuración para Redis en app/config/config.php. Por defecto, el servicio Redis de ServBay está en 127.0.0.1, puerto 6379.

   return new \Phalcon\Config([
       // ... Otras configuraciones ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Índice de la base de datos Redis (por defecto, 0)
           'persistent' => false, // Si usar conexión persistente
           'auth' => null, // Contraseña si Redis lo requiere
       ],
       // ... Otras configuraciones ...
   ]);

3. Agrega una ruta de ejemplo

   Edita app/config/routes.php y añade una ruta para la demostración de caché con Redis:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // Ruta para la demo con Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Utiliza Redis como caché en el controlador

   Completa el método redisAction en app/controllers/IndexController.php para demostrar la funcionalidad de caché con Redis:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Adaptador para Redis
   use Phalcon\Storage\SerializerFactory; // Para serialización
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'Usuario añadido correctamente.' : 'Fallo al añadir usuario.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Ejemplo de caché con Redis
       public function redisAction()
       {
           // Crear instancia del serializer
           $serializerFactory = new SerializerFactory();
   
           // Configuración para Redis (debe coincidir con 'cache' en config.php)
           $options = [
               'defaultSerializer' => 'Json', // Serialización en JSON por defecto
               'lifetime'          => 3600, // Tiempo de vida de la caché (ej: 1 hora)
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'tu_contraseña_redis', // Si tu instancia tiene contraseña
           ];
   
           // Crea la instancia del adaptador Redis
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Recuperar datos en caché
   
           if ($cachedData === null) {
               // Si no existe en caché
               echo "Datos no encontrados en caché, obteniendo desde la fuente...";
               $cachedData = 'Datos obtenidos de la fuente: ¡Hola Redis desde ServBay!';
               $cache->set($cacheKey, $cachedData); // Guarda en caché
               echo "Datos almacenados en la caché.";
           } else {
               // Si existen en caché
               echo "Datos encontrados en caché: ";
           }
   
           // Devuelve los datos (en caché o recién obtenidos)
           return $cachedData;
       }
   }

   Nota: Para proyectos productivos, es aconsejable gestionar la caché como un servicio en el contenedor de dependencias.

5. Accede a la demo

   Abre el navegador y entra a https://servbay-phalcon-test.local/redis.

   • La primera vez verás el mensaje "Datos no encontrados en caché, obteniendo desde la fuente...Datos almacenados en la caché." junto con "Datos obtenidos de la fuente: ¡Hola Redis desde ServBay!".
   • Repite la visita dentro del periodo de validez de la caché y verás "Datos encontrados en caché: " seguido del valor recuperado, mostrando que Redis está funcionando.

Preguntas frecuentes (FAQ)

• P: ¿Qué hago si veo un error 404 Not Found al acceder al sitio?
  • R: Verifica que la “Carpeta raíz del sitio” en la configuración de ServBay apunte al directorio public de tu proyecto Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). También asegúrate de que el servidor web correspondiente (Caddy o Nginx) está en funcionamiento y que la resolución DNS local para el dominio es correcta.
• P: ¿Por qué aparece el error “Class 'Phalcon\Mvc\Application' not found” (módulo Phalcon no encontrado)?
  • R: Normalmente porque la extensión Phalcon no está habilitada para la versión de PHP seleccionada. Vuelve a ServBay, asegúrate de que el módulo Phalcon está activo para la versión correcta y reinicia el servicio PHP. Consulta Cómo habilitar el módulo Phalcon de ServBay.
• P: ¿Qué hago si la conexión a la base de datos falla?
  • R: Verifica los datos en app/config/config.php (host, usuario, contraseña, nombre de la base de datos). Asegúrate de que el servicio de la base de datos está activo y que el usuario tiene permisos para acceder a la base y ya existe dicha base.

Resumen

ServBay facilita enormemente la creación de un entorno local de desarrollo de alto rendimiento con Phalcon. Esta guía ha mostrado cómo generar la estructura del proyecto, configurar el servidor web y conectar bases de datos MySQL y Redis. Gracias a los paquetes integrados y la interfaz de gestión de ServBay, la configuración y el mantenimiento del entorno resultan mucho más sencillos, permitiéndote enfocarte en el desarrollo de tu aplicación en Phalcon. ¡Esperamos que esta guía te ayude a comenzar a desarrollar rápidamente y de manera eficiente webs y APIs con ServBay y Phalcon!