Crear y ejecutar proyectos Phalcon

¿Qué es Phalcon?

Phalcon es un framework web de código abierto y alto rendimiento para PHP, implementado como una extensión en C. Esta arquitectura única le permite alcanzar un consumo de recursos mínimo y una velocidad de ejecución sobresaliente, superando ampliamente a la mayoría de los frameworks PHP tradicionales. Phalcon sigue el patrón arquitectónico MVC (Modelo-Vista-Controlador), ofreciendo a los desarrolladores una amplia variedad de componentes integrados como ORM (Mapeo objeto-relacional), motor de plantillas, enrutado, caché y gestor de eventos, entre otros. Su objetivo es ayudar a crear aplicaciones web y APIs potentes y de alto rendimiento con rapidez.

Principales características y ventajas de Phalcon

• Rendimiento excepcional: Al ejecutarse como una extensión en C, Phalcon evita el coste de parseo y carga de archivos PHP, ofreciendo un rendimiento a nivel nativo.
• Eficiencia en el uso de recursos: Su bajo consumo de memoria lo hace ideal para aplicaciones que requieren alta velocidad y escalabilidad.
• Funcionalidad completa: Incluye la mayoría de los componentes fundamentales para aplicaciones web, reduciendo la dependencia de librerías de terceros.
• Facilidad de uso: Dispone de una API clara y coherente, además de documentación detallada, para que incluso los principiantes lo dominen rápidamente.
• Altamente desacoplado: Los componentes están diseñados de forma independiente, lo que permite elegir o reemplazar partes específicas según tus necesidades.
• Seguridad: Incluye varios componentes de seguridad, como filtrado de entradas y protección CSRF.

Phalcon es ideal para construir aplicaciones web y APIs escalables y de alto rendimiento, especialmente en proyectos que requieren eficiencia y rapidez.

Crear y ejecutar un proyecto Phalcon con ServBay

ServBay es un entorno local de desarrollo web diseñado especialmente para macOS. Permite gestionar fácilmente múltiples versiones de PHP, bases de datos (como MySQL, PostgreSQL, MongoDB, Redis) y servidores web (Caddy, Nginx, Apache), además de otras utilidades para desarrolladores. Con ServBay puedes configurar y gestionar el entorno necesario para proyectos Phalcon de manera sencilla.

Esta guía te lleva paso a paso a crear un proyecto básico en Phalcon usando ServBay, configurar el servidor web para que sea accesible y demostrar cómo integrar una base de datos relacional (MySQL) y una NoSQL (Redis).

Requisitos previos

Antes de empezar, asegúrate de cumplir lo siguiente:

1. ServBay instalado y ejecutándose: Verifica que ServBay esté correctamente instalado y en funcionamiento en tu sistema macOS.
2. Versión de PHP habilitada: Asegúrate de que la versión de PHP que quieres usar está habilitada en ServBay.
3. Módulo Phalcon habilitado: ServBay incluye el módulo de Phalcon, pero puede no estar activado por defecto. Sigue las instrucciones del documento Cómo habilitar el módulo Phalcon integrado en ServBay para activar la extensión Phalcon adecuada para tu versión de PHP y reinicia el servicio PHP.
4. Composer disponible: ServBay incluye Composer, no necesitas instalarlo aparte. Verifica que puedas usar el comando composer directamente desde la terminal.

Versiones de Phalcon y DevTools

Las versiones del framework Phalcon y su herramienta de desarrollo DevTools deben ser compatibles con la versión de PHP que estás usando. La siguiente tabla muestra la relación recomendada entre versiones de PHP, Phalcon y DevTools más habituales:

Versión PHP	Versión recomendada de Phalcon	Versión recomendada de DevTools	Nota
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 presentar problemas de compatibilidad en PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repositorio corregido)	Se recomienda usar la versión corregida de la comunidad para mejor compatibilidad.

Importante: Para PHP 8.x y superiores, las DevTools oficiales pueden ser incompatibles. Es mejor usar las versiones corregidas por la comunidad. En los pasos siguientes se explica cómo instalar las DevTools corregidas vía Composer.

Crear un proyecto Phalcon

Ruta recomendada para tus sitios

Para facilitar la gestión, ServBay recomienda guardar todos los proyectos web en la carpeta raíz por defecto /Applications/ServBay/www. El ejemplo de esta guía se creará en ese directorio.

1. Accede a la carpeta raíz de sitios y crea la carpeta del proyecto

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

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

2. Instala Phalcon DevTools

   Phalcon DevTools es el conjunto de herramientas de línea de comandos para agilizar tareas como generación de código, scaffolding y migraciones. Se instala con Composer, y el comando varía según la versión de PHP:

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • Para PHP 8.0, 8.1, 8.2, 8.3, 8.4 (DevTools dev-master corregidas): Debido a problemas de compatibilidad, usa la versión corregida de la comunidad. Crea o edita el archivo composer.json en la carpeta raíz del proyecto y añade el repositorio corregido:

     {
        "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
     }

     Luego ejecuta la actualización con Composer:

     composer update

   Composer creará una carpeta vendor en la raíz (servbay-phalcon-app), y el ejecutable de DevTools estará en vendor/bin/phalcon.

3. Crea la estructura base ("scaffolding") del proyecto con DevTools

   Usa el comando recién instalado para generar la estructura base del proyecto Phalcon. El código se ubicará en un subdirectorio (normalmente llamado igual que la carpeta inicial):

   vendor/bin/phalcon project servbay-phalcon-app

   Esto crea un nuevo subdirectorio /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app con la estructura completa de un proyecto Phalcon.

4. Entra en la carpeta de código del proyecto

   Cambia a la carpeta donde se generó el proyecto:

   cd servbay-phalcon-app

   Ahora estás en /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configuración del entorno del proyecto

La configuración principal del proyecto Phalcon se encuentra en el archivo app/config/config.php. Aquí debes definir los datos de acceso a la base de datos y rutas importantes.

1. Edita el archivo de configuración

   Usa tu editor favorito para abrir /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php. Busca o añade la sección de la base de datos. El usuario por defecto de MySQL/MariaDB en ServBay es root con contraseña vacía, pero por seguridad se recomienda usar una contraseña fuerte. El ejemplo usa password como marcador, cámbialo según tu configuración real. El nombre de la base servbay_phalcon_app es solo un ejemplo (créala 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 tu contraseña
           'dbname' => 'servbay_phalcon_app', // <-- Cambia por tu base de datos
       ],
       // ... otras configuraciones ...
   ]);

   Importante: Verifica que el servicio de base de datos (MySQL/MariaDB) está iniciado en ServBay y que los datos coinciden con la configuración. Debes crear manualmente la base de datos, si no existe, usando phpMyAdmin o Adminer.

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

Para acceder a tu proyecto Phalcon desde el navegador, configura un virtual host usando la función Sitios de ServBay y apunta al directorio accesible por la web.

1. Abre la app ServBay
2. Entra a la sección 'Sitios': En la pantalla principal, busca y haz clic en 'Sitios'.
3. Añade un nuevo sitio:
   • Nombre: Escribe uno fácil de identificar, por ejemplo My First Phalcon Dev Site.
   • Dominio: Introduce el dominio que quieres usar en el navegador, como servbay-phalcon-test.local. ServBay resuelve automáticamente los .local a tu entorno local.
   • Tipo de sitio: Selecciona PHP.
   • Versión de PHP: Elige la misma versión que tiene habilitado el módulo Phalcon para tu proyecto.
   • Raíz del sitio web: Este es el paso clave. El archivo index.php de Phalcon normalmente está en la carpeta public, así que apunta la raíz a /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Guarda la configuración. ServBay aplicará los cambios automáticamente, puede ser necesario reiniciar el servidor web (Caddy o Nginx).

Para más detalles, consulta Cómo añadir tu primer sitio web. ServBay se encargará de la resolución del dominio local y los ajustes del servidor web propios.

Añadir código de ejemplo

Vamos a agregar una ruta y controlador básicos para probar el funcionamiento del proyecto.

1. Configura una ruta

   Edita /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php, y añade una regla de ruta simple para la raíz /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Define la ruta predeterminada, mapeando '/' al método indexAction de IndexController
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... puedes añadir más rutas aquí ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crea el controlador

   Edita /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php (créalo si no existe) y añade el método indexAction:

   <?php
   namespace App\Controllers; // Verifica que el namespace es correcto
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Maneja las peticiones a '/'
       public function indexAction()
       {
           // Retorna un texto simple como respuesta
           return 'Hello ServBay!';
       }
   }

Acceso al sitio web

Guarda todos los archivos y verifica que ServBay esté corriendo. Abre tu navegador y ve al dominio configurado en ServBay:

https://servbay-phalcon-test.local

Si todo está bien configurado, deberías ver como respuesta: Hello ServBay!.

Integración con bases de datos

Phalcon ofrece una capa de abstracción de base de datos potente y un ORM propio. ServBay integra múltiples bases, así que puedes conectarlas fácilmente a tu proyecto Phalcon. Usaremos de ejemplo MySQL y Redis.

Ejemplo relacional con MySQL

Aquí verás cómo conectar Phalcon con el servicio MySQL de ServBay y realizar operaciones básicas de inserción y consulta.

1. Crea la estructura de la base (usando migraciones)

   Las migraciones de Phalcon DevTools te permiten controlar el estado y versiones del esquema de la base de datos.

   • Genera un archivo de migración: Desde la carpeta del código del proyecto (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app), ejecuta este comando para crear una migración vacía:

     vendor/bin/phalcon migration generate

     Esto generará un archivo nuevo en la carpeta migrations con un nombre tipo YYYYMMDDHHMMSS_NombreMigracion.php.

   • Edita el archivo de migración: Abre el archivo creado y edita el método morph para definir la tabla users:

     <?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 debe coincidir con el del archivo
     {
         /**
          * Ejecuta las migraciones
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Reversa las migraciones
          *
          * @return void
          */
         public function down()
         {
             // Opcional: lógica para revertir la migración, por ejemplo, eliminar la tabla
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: Confirma que el nombre de la clase (UsersMigration_100) coincide con el del archivo. Incluye el timestamp más el nombre.

   • Ejecuta la migración: Ejecuta este comando para aplicar la migración y crear la tabla en la base de datos:

     vendor/bin/phalcon migration run

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

2. Configura la conexión a la base de datos (ya se cubrió anteriormente)

   Confirma que la sección 'database' en app/config/config.php apunta correctamente al servicio MySQL/MariaDB de ServBay (host 127.0.0.1, puerto 3306, usuario root y la contraseña que definiste).

3. Agrega rutas de ejemplo

   Edita app/config/routes.php y añade rutas para insertar y consultar usuarios:

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

4. Implementa las operaciones en el controlador

   Edita app/controllers/IndexController.php y agrega los métodos mysqlAddAction y mysqlAction, usando el servicio de base de datos de Phalcon:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Adaptador para MySQL
   use Phalcon\Db\Enum; // Constantes para fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Ejemplo de inserción de usuario
       public function mysqlAddAction()
       {
           // Obtén la conexión a la base de datos
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Cambia por tu contraseña
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Inserta un usuario de ejemplo
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', 'demo@servbay.test'],
               ['name', 'email']
           );
   
           // Muestra el resultado
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Ejemplo de consulta
       public function mysqlAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Cambia por tu contraseña
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Consulta todos los usuarios
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Resultado en formato JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Nota: En producción es mejor registrar la conexión en el contenedor de servicios (DI) y reutilizarla en los controladores mediante inyección de dependencias.

5. Accede a los ejemplos

   • Desde el navegador, accede a https://servbay-phalcon-test.local/mysql-add. Si todo está bien, verás "User added successfully.".
   • Luego entra en https://servbay-phalcon-test.local/mysql. Deberías ver los datos de la tabla users en JSON, incluyendo el usuario recién insertado.

Ejemplo NoSQL con Redis

Aquí verás cómo usar Redis como caché en tu proyecto Phalcon gracias a la integración de ServBay.

1. Instala/extiende Redis

   ServBay ya suele incluir el módulo Redis para PHP. Solo verifica que hayas habilitado la extensión Redis para la versión de PHP que uses en ServBay.

2. Configura la conexión a Redis

   Añade la configuración de Redis en app/config/config.php. ServBay pone Redis en 127.0.0.1 puerto 6379 por defecto.

   return new \Phalcon\Config([
       // ... otras configuraciones ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // Añade contraseña si corresponde
       ],
       // ... otras configuraciones ...
   ]);

3. Agrega ruta de ejemplo

   Edita app/config/routes.php, y añade una ruta para probar Redis como caché:

   <?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 probar Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Usa Redis como caché en el controlador

   Edita app/controllers/IndexController.php y añade el método redisAction:

   <?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; // Fábrica de serializadores
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       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()
       {
           // Crea el serializador
           $serializerFactory = new SerializerFactory();
   
           // Configura opciones de Redis para el caché
           // Deben ser igual a las de 'cache' en config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'tu_contraseña_redis', // Si usas autenticación
           ];
   
           // Instancia el adaptador Redis
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Intenta obtener datos del caché
   
           if ($cachedData === null) {
               // Si no hay datos en caché
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData);
               echo "Data stored in cache.";
           } else {
               // Si hay datos en caché
               echo "Data found in cache: ";
           }
   
           // Retorna los datos (del caché o de la fuente)
           return $cachedData;
       }
   }

   Nota: Lo habitual es configurar el caché en el contenedor DI para accederlo desde cualquier parte de la aplicación, no sólo desde el controlador.

5. Prueba el ejemplo

   Entra en el navegador a https://servbay-phalcon-test.local/redis.

   • La primera vez verás "Data not found in cache, fetching from source...Data stored in cache." y "Data fetched from source: Hello Redis from ServBay!".
   • Si vuelves a acceder antes que caduque el caché, verás "Data found in cache: " y "Data fetched from source: Hello Redis from ServBay!", indicando que consiguió los datos de Redis.

Preguntas frecuentes (FAQ)

• P: ¿Qué hago si aparece el error 404 Not Found al acceder al sitio?
  • R: Asegúrate de que la raíz del sitio en la configuración de ServBay apunte a la carpeta public de tu proyecto Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Verifica que el servidor web (Caddy o Nginx) esté corriendo y que el dominio local se resuelve correctamente.
• P: ¿Cómo solucionar el error de módulo Phalcon no encontrado (Class 'Phalcon\Mvc\Application' not found)?
  • R: Usualmente significa que la extensión Phalcon no está activa en la versión de PHP en uso. Vuelve a ServBay y verifica que la extensión Phalcon esté habilitada para esa versión de PHP, luego reinicia el servicio PHP. Revisa Cómo habilitar el módulo Phalcon que viene con ServBay.
• P: ¿Qué hago si falla la conexión a la base de datos?
  • R: Revisa la configuración en app/config/config.php (host, usuario, contraseña, nombre de base) y verifica que el servicio MySQL/MariaDB está activo en ServBay. Confirma que el usuario tiene permisos sobre la base y que la base existe.

Resumen

ServBay te permite montar fácilmente un entorno local de alto rendimiento para trabajar con el framework Phalcon. Esta guía mostró cómo crear la estructura base del proyecto, configurar el servidor web y conectar MySQL y Redis con Phalcon. El amplio conjunto de paquetes y la interfaz de gestión de ServBay simplifican la configuración y el mantenimiento del entorno local, permitiéndote concentrarte en el desarrollo de tus aplicaciones Phalcon. ¡Esperamos que esta guía te ayude a comenzar de forma efectiva tu desarrollo web con ServBay y Phalcon!