Créer et exécuter un projet Phalcon

Qu'est-ce que Phalcon ?

Phalcon est un framework web open-source pour PHP, réputé pour ses hautes performances, développé sous forme d'extension en C. Cette approche innovante permet à Phalcon d’atteindre une consommation minimale de ressources et une rapidité d’exécution remarquable, surpassant les frameworks PHP traditionnels. Basé sur une architecture MVC (Modèle-Vue-Contrôleur), Phalcon propose une suite complète de composants : ORM (mapping objet-relationnel), moteur de templates, routing, cache, gestionnaire d'évènements, etc. Son but est d’aider les développeurs à bâtir rapidement des applications web et des API puissantes et performantes.

Principales caractéristiques et avantages de Phalcon

• Performance exceptionnelle : Fonctionnant comme une extension C, Phalcon évite la surcharge de l’analyse et du chargement des scripts PHP, offrant des performances natives.
• Efficience des ressources : Occupation mémoire extrêmement basse, idéal pour les applications nécessitant vitesse et scalabilité.
• Richesse fonctionnelle : L’essentiel des modules nécessaires au développement web sont intégrés, limitant la dépendance aux bibliothèques tierces.
• Facilité d’utilisation : Une API claire et cohérente, une documentation exhaustive permettent une prise en main rapide, même pour les débutants.
• Modularité poussée : Chaque composant est indépendant, offrant la liberté de les utiliser ou de les remplacer selon les besoins du projet.
• Sécurité : Intègre de nombreux outils dédiés à la sécurité : filtrage des entrées, protection CSRF, etc.

Phalcon est le choix idéal pour réaliser des applications web ou API performantes et évolutives, en particulier lorsque la rapidité et l’efficacité des ressources sont des critères clés.

Créer et exécuter un projet Phalcon avec ServBay

ServBay est un environnement de développement web local pour macOS, rassemblant plusieurs versions de PHP, des bases de données (MySQL, PostgreSQL, MongoDB, Redis) ainsi que des serveurs web (Caddy, Nginx, Apache) et de nombreux outils pour développeurs. Avec ServBay, vous pouvez facilement configurer et superviser l’environnement requis pour vos projets Phalcon.

Ce guide vous accompagne pour créer un projet Phalcon basique avec l’environnement PHP de ServBay, configurer le serveur web pour le rendre accessible et intégrer une base relationnelle (MySQL) et une base NoSQL (Redis).

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

1. ServBay installé et fonctionnel : Assurez-vous que ServBay est bien installé et lancé sur votre système macOS.
2. Version PHP nécessaire activée : Vérifiez dans ServBay que la version de PHP souhaitée est activée.
3. Module Phalcon activé : ServBay inclut Phalcon, mais il peut être désactivé par défaut. Suivez la documentation Activer le module Phalcon fourni par ServBay pour activer l’extension Phalcon sur la version PHP de votre projet, puis redémarrez le service PHP.
4. Composer disponible : ServBay installe Composer automatiquement, donc inutile de l’installer séparément. Assurez-vous que la commande composer fonctionne dans votre terminal.

Versions de Phalcon et DevTools

La version du framework Phalcon et celle de ses DevTools doivent correspondre à celle de PHP que vous utilisez. Voici un tableau indiquant les relations recommandées entre les versions de PHP, Phalcon et DevTools :

Version PHP	Version Phalcon recommandée	Version DevTools recommandée	Notes
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 (ou 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (officiel)	Compatibilité parfois limitée des DevTools sur PHP 8.x
PHP 8.3, 8.4	Phalcon 5.x	dev-master (version corrigée)	Usage conseillé de la version corrigée communautaire

Note importante : Pour PHP 8.x et supérieur, la version officielle des DevTools présente parfois des incompatibilités. Utilisez la version corrigée proposée par la communauté ; les étapes suivantes décrivent son installation via Composer.

Créer un projet Phalcon

Chemin recommandé pour les sites

ServBay recommande de placer tous vos projets web dans le répertoire racine par défaut /Applications/ServBay/www pour en faciliter la gestion. L’exemple ci-après utilise ce dossier.

1. Accédez au dossier racine et créez le dossier projet

   Ouvrez le terminal, placez-vous dans le répertoire racine du web ServBay, puis créez un nouveau dossier pour votre projet Phalcon (par exemple servbay-phalcon-app) :

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

2. Installation de Phalcon DevTools

   Phalcon DevTools est une suite d’outils en ligne de commande pour générer du code rapidement, créer l’ossature du projet, gérer les migrations, etc. Installez-le via Composer selon la version PHP choisie :

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • Pour PHP 8.0 et supérieur (DevTools dev-master version corrigée) : La version officielle des DevTools pouvant poser problème avec PHP 8.x, ajoutez le dépôt communautaire dans le fichier composer.json à la racine de votre projet (/Applications/ServBay/www/servbay-phalcon-app) :

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

     Puis lancez la mise à jour Composer pour installer DevTools :

     composer update

   Un dossier vendor sera créé à la racine (servbay-phalcon-app), avec le fichier exécutable DevTools dans vendor/bin/phalcon.

3. Générer la structure du projet avec DevTools

   Utilisez la commande DevTools pour générer la structure de base du projet Phalcon. Le code du projet sera généré dans un sous-dossier (également nommé servbay-phalcon-app par défaut) :

   vendor/bin/phalcon project servbay-phalcon-app

   Cette commande crée le sous-dossier /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app, contenant l’ossature complète du projet.

4. Accédez au dossier code du projet

   Entrez dans le dossier du code du projet ; toutes les opérations suivantes s’y dérouleront :

   cd servbay-phalcon-app

   Vous êtes maintenant dans /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configurer l’environnement du projet

La configuration d’un projet Phalcon se trouve généralement dans le fichier app/config/config.php. On y définit les paramètres de connexion à la base de données, les chemins de l’application, etc.

1. Modifier le fichier de configuration

   Ouvrez /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php avec votre éditeur favori et complétez la section destinée à la base de données. Par défaut, ServBay propose l’utilisateur MySQL/MariaDB root sans mot de passe, mais il est conseillé de définir un mot de passe robuste. Dans l’exemple, le mot de passe est password, modifiez-le selon votre configuration. Le nom de la base servbay_phalcon_app doit être créé manuellement.

   return new \Phalcon\Config([
       // ... autres configurations ...
       'database' => [
           'adapter' => 'Mysql', // Ou 'Postgres', etc.
           'host' => '127.0.0.1',
           'username' => 'root', // Utilisateur root par défaut ServBay
           'password' => 'password', // <-- À remplacer par votre mot de passe
           'dbname' => 'servbay_phalcon_app', // <-- À adapter selon votre base
       ],
       // ... autres configurations ...
   ]);

   Important : Vérifiez que le service base de données (MySQL ou MariaDB) est lancé sous ServBay et que les identifiants correspondent. Créez également la base servbay_phalcon_app à l’aide d’outils comme phpMyAdmin ou Adminer inclus avec ServBay.

Configuration du serveur web via ServBay

Pour accéder au projet Phalcon via navigateur, créez un hôte virtuel grâce à la fonction Sites de ServBay, en le redirigeant vers le dossier web public du projet.

1. Ouvrez l’application ServBay
2. Allez dans la section ‘Sites’ : Cliquez sur l'entrée ‘Sites’ dans l’interface principale.
3. Ajoutez un nouveau site :
   • Nom : Choisissez un nom évocateur, ex : Mon premier site Phalcon
   • Domaine : Indiquez le domaine souhaité, ex : servbay-phalcon-test.local (ServBay résout automatiquement le .local en local).
   • Type de site : Sélectionnez PHP.
   • Version PHP : Choisissez celle qui dispose du module Phalcon activé.
   • Racine du site : Indiquez le dossier public contenant le index.php : /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Sauvegardez la configuration : ServBay appliquera les changements ; vous devrez peut-être redémarrer le serveur web (Caddy ou Nginx).

Pour plus de détails, consultez Ajouter un premier site. Une fois configuré, ServBay gérera automatiquement la résolution du nom de domaine et la configuration du serveur web.

Ajouter un code de vérification

Ajoutez un exemple de code simple pour vérifier le bon fonctionnement du projet.

1. Configurer une route

   Dans /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php, ajoutez une règle pour gérer la racine / :

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Définit la route par défaut, qui relie la racine '/' à indexAction du contrôleur IndexController
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... Autres règles de routing possibles ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Créer le contrôleur

   Dans /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php (à créer si absent), ajoutez un indexAction simple :

   <?php
   namespace App\Controllers; // Vérifiez le namespace
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Gère la route racine '/'
       public function indexAction()
       {
           // Retourne une chaîne simple en réponse
           return 'Hello ServBay!';
       }
   }

Accéder au site

Sauvegardez tous les fichiers puis assurez-vous que ServBay fonctionne. Ouvrez un navigateur et rendez-vous à l’adresse configurée :

https://servbay-phalcon-test.local

Si la configuration est correcte, le message Hello ServBay! s’affichera.

Intégrer les bases de données

Phalcon possède une couche d’abstraction et un ORM puissants. ServBay propose plusieurs bases intégrées que vous pouvez facilement relier à vos projets Phalcon. Voici des exemples avec MySQL et Redis.

Exemple base de données relationnelle : MySQL

Voyons comment utiliser l’adaptateur MySQL de Phalcon pour se connecter au service MySQL de ServBay, avec insertion et affichage de données.

1. Créer la structure de la base (par migration)

   Les migrations DevTools, utiles pour la gestion des versions de schéma, peuvent générer la structure de la base.

   • Générer un fichier de migration : Dans le dossier projet (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app), exécutez :

     vendor/bin/phalcon migration generate

     Un nouveau fichier migration sera créé (ex : YYYYMMDDHHMMSS_MigrationName.php) dans migrations.

   • Modifier le fichier migration : Complétez la méthode morph pour une table users :

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Le nom de classe doit correspondre au fichier
     {
         /**
          * Exécute la migration
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Pour annuler la migration
          *
          * @return void
          */
         public function down()
         {
             // Optionnel : logiques de rollback, par exemple supprimer la table
             // $this->getConnection()->dropTable('users');
         }
     }

     Remarque : Veillez à ce que le nom de classe (ex : UsersMigration_100) corresponde à celui du fichier migration.

   • Exécuter la migration : Lancez la commande depuis le dossier projet pour créer la table :

     vendor/bin/phalcon migration run

     En cas d’erreur de connexion, vérifiez la configuration de la base dans app/config/config.php et le statut du service MySQL/MariaDB ServBay.

2. Configurer la connexion (déjà fait plus haut)

   Vérifiez la section 'database' de app/config/config.php (hôte, port, utilisateur, mot de passe, base).

3. Ajouter les routes d’exemple

   Dans app/config/routes.php, ajoutez les routes pour insérer et consulter les utilisateurs :

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Route pour l’insertion d’utilisateur
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Route pour la liste des utilisateurs
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implémenter les actions en base de données

   Dans app/controllers/IndexController.php, créez mysqlAddAction et mysqlAction. On utilise ici la connexion directe à la base Phalcon :

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Importer l’adaptateur MySQL
   use Phalcon\Db\Enum; // Pour le mode de fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Exemple d’insertion utilisateur
       public function mysqlAddAction()
       {
           // Connexion rapide à la base (dans les vraies applis, préférez l’injection via le conteneur de services)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- À adapter à votre mot de passe
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Ajoute un utilisateur démo
           $success = $connection->insert(
               'users', // table
               ['ServBay Demo User', 'demo@servbay.test'], // valeurs
               ['name', 'email'] // colonnes
           );
   
           // Affiche le résultat
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Liste des utilisateurs
       public function mysqlAction()
       {
            // Connexion à la base
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password',
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Sélectionne tous les utilisateurs
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Affiche en JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Remarque : En production, il vaut mieux configurer la connexion dans le conteneur de services et injecter la dépendance dans le contrôleur.

5. Testez l’exemple

   • Rendez-vous sur https://servbay-phalcon-test.local/mysql-add dans le navigateur. Si tout va bien, le message "User added successfully." apparaît.
   • Accédez à https://servbay-phalcon-test.local/mysql pour voir les contenus du tableau users au format JSON.

Exemple base de données NoSQL : Redis

Voyons comment utiliser Redis en tant que cache dans Phalcon avec ServBay :

1. Activer l’extension Redis

   ServBay inclut normalement l’extension Redis dans la plupart des packs PHP. Vérifiez simplement qu’elle est activée sur la version de PHP utilisée.

2. Configurer la connexion Redis

   Ajoutez la configuration dans app/config/config.php. Par défaut, ServBay héberge Redis sur 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... autres configurations ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // À compléter si un mot de passe est défini
       ],
       // ... autres configurations ...
   ]);

3. Ajouter une route d’exemple

   Ajoutez dans app/config/routes.php une route pour tester le cache 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',
   ]);
   
   // Route de démonstration du cache Redis
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Utiliser Redis dans le contrôleur

   Ajoutez la méthode redisAction dans app/controllers/IndexController.php :

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Importation de Redis
   use Phalcon\Storage\SerializerFactory; // Pour la sérialisation
   
   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);
       }
   
       // Exemple de cache Redis
       public function redisAction()
       {
           // Instance du sérialiseur
           $serializerFactory = new SerializerFactory();
   
           // Options du cache Redis
           // Assurez-vous que ces options correspondent à celles du fichier config
           $options = [
               'defaultSerializer' => 'Json', // Utilisation de JSON pour sérialiser
               'lifetime'          => 3600,   // Durée de cache en secondes
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'votre_mot_de_passe_redis', // si nécessaire
           ];
   
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // Récupère le cache
   
           if ($cachedData === null) {
               // Si le cache est vide
               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 données en cache
               echo "Data found in cache: ";
           }
   
           // Retourne les données
           return $cachedData;
       }
   }

   Remarque : Comme pour la base SQL, il est recommandé de configurer le cache en tant que service injectable dans l’application.

5. Tester l’exemple

   Accédez à https://servbay-phalcon-test.local/redis dans le navigateur.

   • Première visite : le message "Data not found in cache, fetching from source...Data stored in cache." apparaît, suivi de "Data fetched from source: Hello Redis from ServBay!".
   • Pour les accès suivants (tant que le cache est valide), vous verrez "Data found in cache: " et "Data fetched from source: Hello Redis from ServBay!", preuve que le résultat vient de Redis.

Foire aux questions (FAQ)

• Q : Que faire en cas d'erreur 404 Not Found lors de l’accès au site ?
  • R : Vérifiez que le champ “racine du site” dans la configuration ServBay pointe bien vers le dossier public du projet (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Assurez-vous aussi que le serveur web (Caddy ou Nginx) tourne et que le domaine est bien résolu localement.
• Q : Erreur Phalcon module non trouvé (Class 'Phalcon\Mvc\Application' not found etc.) ?
  • R : Cela indique généralement que l’extension Phalcon n’est pas activée sur la version PHP utilisée. Retournez dans ServBay, activez le module Phalcon pour la version PHP du projet et redémarrez le service. Voir Activer le module Phalcon ServBay.
• Q : Échec de connexion à la base de données ?
  • R : Contrôlez la configuration 'database' dans app/config/config.php (hôte, utilisateur, mot de passe, nom de base). Vérifiez que le service MySQL/MariaDB est lancé sous ServBay et que l’utilisateur a les droits nécessaires, et que la base existe.

Conclusion

Grâce à ServBay, il est facile de mettre en place un environnement local performant et propulsé par le framework Phalcon. Ce guide vous aura montré comment générer la structure du projet, configurer le serveur web pour le rendre accessible, et intégrer aisément MySQL et Redis. ServBay, avec ses nombreux paquets et son interface de gestion conviviale, simplifie la configuration et la maintenance, vous permettant de vous concentrer sur le développement de votre application Phalcon. Nous espérons que ce guide vous accompagnera efficacement dans vos premiers pas avec ServBay et Phalcon pour développer des applications web rapides et fiables !