Créer et exécuter un projet Phalcon

Qu'est-ce que Phalcon ?

Phalcon est un framework web PHP open-source et ultra-performant, implémenté sous forme d'une extension C. Cette approche unique permet à Phalcon de consommer très peu de ressources et d'offrir une vitesse d’exécution exceptionnelle, surpassant la plupart des frameworks PHP traditionnels. Respectant l’architecture MVC (Modèle-Vue-Contrôleur), Phalcon propose un ensemble de composants complets pour le développement : ORM, moteur de templates, routage, cache, gestionnaire d’événements, etc., afin d’aider les développeurs à bâtir rapidement des applications web et API puissantes et performantes.

Principales fonctionnalités et avantages de Phalcon

• Performance exceptionnelle : Fonctionnant en tant qu’extension C, Phalcon évite la surcharge de parsing et de chargement des scripts PHP et offre des performances dignes du natif.
• Efficacité des ressources : Occupation mémoire extrêmement faible, idéal pour les applications exigeant scalabilité et rapidité.
• Complet : Intègre en natif la plupart des composants incontournables pour les applications web, limitant la dépendance aux bibliothèques tierces.
• Facile à utiliser : API claire et cohérente, documentation détaillée, une prise en main rapide même pour les débutants.
• Haute modularité : Composants découplés, libre choix dans leur usage ou leur remplacement.
• Sécurité : Vaste éventail de fonctionnalités de sécurité : filtrage d'entrées, protection CSRF, etc.

Phalcon est un choix idéal pour créer des applications web et API à la fois performantes et évolutives, particulièrement dans les projets nécessitant une efficacité maximale.

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

ServBay est un environnement de développement web local conçu pour macOS, intégrant différentes versions de PHP, plusieurs bases de données (MySQL, PostgreSQL, MongoDB, Redis) ainsi que des serveurs web (Caddy, Nginx, Apache) et d’autres outils pour développeurs. Grâce à ServBay, vous pouvez facilement mettre en place et gérer l’environnement nécessaire à vos projets Phalcon.

Ce guide vous accompagne pour créer un projet Phalcon basique avec PHP sous ServBay, configurer le serveur web, et intégrer une base de données relationnelle (MySQL) ainsi qu’une base NoSQL (Redis).

Prérequis

Assurez-vous d’avoir :

1. ServBay installé et lancé : ServBay doit être correctement installé et démarré sur votre système macOS.
2. Version PHP requise activée : Vérifiez que la version de PHP que vous souhaitez utiliser est active dans ServBay.
3. Module Phalcon activé : Le module Phalcon est préinstallé dans ServBay, mais peut nécessiter une activation manuelle. Suivez la documentation Comment activer le module Phalcon de ServBay pour activer l’extension correspondante, puis redémarrez le service PHP.
4. Composer disponible : ServBay intègre Composer, vous n’avez pas besoin de l’installer séparément. Veillez à pouvoir exécuter la commande composer dans votre terminal.

Versions de Phalcon et DevTools

Le framework Phalcon et ses outils de développement (Phalcon DevTools) doivent être compatibles avec la version de PHP utilisée. Le tableau ci-dessous vous guide dans l'association des versions de PHP, de Phalcon et de DevTools recommandées :

Version PHP	Version Phalcon recommandée	Version DevTools recommandée	Remarques
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)	DevTools officiel parfois incompatible avec PHP 8.x.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (version corrigée)	Recommandé : utiliser la version communautaire pour une meilleure compatibilité.

Important : Pour PHP 8.x+, la compatibilité de DevTools officiel peut être partielle ou problématique. Il est recommandé d’utiliser la version corrigée communautaire, comme expliqué dans les instructions suivantes.

Création d’un projet Phalcon

Chemin conseillé pour vos sites

Pour une gestion optimale, ServBay recommande de placer tous vos projets sites dans le dossier racine /Applications/ServBay/www. L’exemple ci-dessous suivra ce principe.

1. Se positionner dans le dossier racine web et créer un dossier de projet

   Ouvrez un terminal, placez-vous dans le dossier racine des sites ServBay, puis créez un dossier pour votre projet Phalcon (ex : servbay-phalcon-app) :

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

2. Installer Phalcon DevTools

   Phalcon DevTools est une suite d’outils CLI facilitant la génération de code, la création de squelettes de projets, la gestion des migrations, etc. Nous l’installerons avec Composer. Selon votre version de PHP, la commande varie :

   • 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. (DevTools dev-master corrigé) : Etant donné que DevTools officiel peut ne pas être compatible PHP 8.x, nous utiliserons la version communautaire corrigée. Créez ou éditez le fichier composer.json à la racine de votre projet :

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

     Ensuite, exécutez :

     composer update

   Composer va créer un dossier vendor à la racine du projet, le binaire de DevTools sera accessible via vendor/bin/phalcon.

3. Générer le squelette du projet avec DevTools

   Lancez la commande suivante pour générer l’architecture de base de votre projet Phalcon. Le code sera souvent placé dans un sous-dossier portant le même nom, c'est le comportement par défaut de DevTools :

   vendor/bin/phalcon project servbay-phalcon-app

   Cette commande crée un nouveau sous-dossier /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app contenant le squelette complet du projet Phalcon.

4. Se positionner dans le dossier code du projet

   Accédez au dossier du code source nouvellement généré pour les étapes suivantes :

   cd servbay-phalcon-app

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

Configuration de l’environnement du projet

La configuration du projet Phalcon se gère principalement dans le fichier app/config/config.php. C’est ici que l’on renseigne les paramètres essentiels : connexion base de données, chemins, etc.

1. Modifier le fichier de configuration

   Ouvrez /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php dans votre éditeur favori. Retrouvez ou ajoutez la section de configuration base de données. ServBay utilise par défaut l’utilisateur root sans mot de passe pour MySQL/MariaDB, mais il est vivement recommandé de définir un mot de passe fort. L’exemple utilise password à titre d’illustration : adaptez ce champ selon votre configuration. Le nom de base servbay_phalcon_app correspond à la base créée pour le projet (à créer vous-même).

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

   Important : Assurez-vous que le service de base de données (MySQL/MariaDB) est démarré dans ServBay, et que l’utilisateur/MDP correspondent. Créez la base servbay_phalcon_app si nécessaire, via les outils d’administration ServBay (phpMyAdmin, Adminer…).

Configuration du serveur web (via la fonction « Sites » de ServBay)

Pour accéder à votre projet Phalcon via un navigateur, utilisez la fonction Sites de ServBay pour configurer un hôte virtuel pointant vers le dossier web approprié.

1. Ouvrir l’application ServBay
2. Aller dans le menu "Sites" : Cliquez sur « Sites » depuis l’interface principale.
3. Ajouter un nouveau site :
   • Nom : Ex : Mon Premier Site Phalcon
   • Domaine : Ex : servbay-phalcon-test.local (ServBay gère automatiquement la résolution du .local)
   • Type de site : Choisissez PHP.
   • Version PHP : Sélectionnez celle pour laquelle le module Phalcon est activé.
   • Racine du site : Définissez le dossier racine sur le dossier public de votre projet : /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public
4. Sauvegarder : ServBay applique automatiquement les modifications ; un redémarrage du serveur web (Caddy ou Nginx) peut être nécessaire.

Pour plus de détails, voir Ajouter son premier site. La résolution du domaine et la configuration du serveur web sont gérées de façon transparente.

Ajout d’un code d’exemple

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

1. Configurer le routage

   Modifiez /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php pour ajouter une règle gérant la racine / :

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Définir la route par défaut, associant '/' à IndexController::indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... autres règles routes éventuelles ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Créer un contrôleur

   Vérifiez ou créez /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php avec le code suivant :

   <?php
   namespace App\Controllers; // Vérifiez le namespace
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Gérer la requête racine '/'
       public function indexAction()
       {
           // Retourner une réponse texte simple
           return 'Hello ServBay!';
       }
   }

Accéder au site

Après avoir sauvegardé tous les fichiers et lancé ServBay, ouvrez votre navigateur et rendez-vous à l’URL configurée :

https://servbay-phalcon-test.local

Vous devrez voir s’afficher Hello ServBay! dans votre navigateur si tout est bien configuré.

Intégration d'une base de données

Phalcon offre une puissante couche d’abstraction et un ORM. ServBay intègre plusieurs bases, facilitant leur utilisation avec Phalcon. Exemple avec MySQL et Redis.

Exemple de base relationnelle : MySQL

Nous allons connecter Phalcon à MySQL de ServBay et exécuter quelques manipulations (insertion, consultation).

1. Créer la structure en base (via migration)

   DevTools gère des migrations pour versionner l’évolution du schéma.

   • Générer le fichier de migration :

     vendor/bin/phalcon migration generate

     Cela crée un fichier de migration dans migrations/, du type YYYYMMDDHHMMSS_MigrationName.php.

   • Éditer la migration pour y définir une table simple 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 doit correspondre au fichier
     {
         /**
          * Exécuter 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',
                 ],
             ]);
         }
     
         /**
          * Rollback
          *
          * @return void
          */
         public function down()
         {
             // Optionnel : implémenter la logique de rollback (ex : supprimer la table)
             // $this->getConnection()->dropTable('users');
         }
     }

     Note : Veillez à ce que le nom de la classe (ex : UsersMigration_100) corresponde à celui du fichier généré.

   • Exécuter la migration pour créer la table :

     vendor/bin/phalcon migration run

     Si vous avez des erreurs de connexion, revérifiez le fichier de configuration et le statut du service MySQL/MariaDB.

2. Vérifier la config de connexion (déjà effectuée plus haut)

   Vérifiez la section 'database' dans app/config/config.php (127.0.0.1, port 3306, utilisateur root, mot de passe, base, etc.).

3. Ajouter des routes d’exemple

   Modifiez app/config/routes.php et ajoutez :

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Route pour ajouter un utilisateur
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Route pour afficher les utilisateurs
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implémenter la logique d’accès à la base dans le contrôleur

   Dans app/controllers/IndexController.php, ajoutez deux méthodes pour l’ajout et la lecture de données utilisateurs :

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Import du connecteur MySQL
   use Phalcon\Db\Enum; // Import pour les constantes de fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Exemple d’insertion d’un utilisateur
       public function mysqlAddAction()
       {
           // Connexion manuelle à la base
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Remplacez par votre mot de passe
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4', // Recommandé
           ]);
   
           // Insertion d’un utilisateur
           $success = $connection->insert(
               'users', // nom de la table
               ['ServBay Demo User', 'demo@servbay.test'], // données
               ['name', 'email'] // champs à renseigner
           );
   
           // Affichage du résultat
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Exemple de récupération d’utilisateurs
       public function mysqlAction()
       {
            // Connexion à la base
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Remplacez par votre mot de passe
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4', // Recommandé
           ]);
   
           // Sélection des utilisateurs
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // Renvoi du résultat au format JSON
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   À savoir : En pratique, il est conseillé de centraliser la connexion via le conteneur de services et l’injection de dépendances.

5. Tester

   • Accédez à https://servbay-phalcon-test.local/mysql-add pour insérer : si succès, "User added successfully."
   • Puis à https://servbay-phalcon-test.local/mysql pour récupérer les enregistrements au format JSON.

Exemple NoSQL : Redis

Démonstration de l’utilisation de Redis comme cache avec ServBay et Phalcon.

1. Extension Redis activée

   Les packages PHP ServBay incluent d’office l’extension Redis. Assurez-vous que votre version PHP active bien l’extension.

2. Configurer la connexion

   Ajoutez la config Redis à app/config/config.php :

   return new \Phalcon\Config([
       // ... autres configurations ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null, // Mot de passe éventuel
       ],
       // ... autres configurations ...
   ]);

3. Définir une route d’exemple

   Dans app/config/routes.php, ajoutez :

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

4. Utiliser Redis dans le contrôleur

   Dans app/controllers/IndexController.php, ajoutez la méthode de démonstration Redis :

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Import de l'adaptateur Redis
   use Phalcon\Storage\SerializerFactory; // Import du sérialiseur
   
   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 cache Redis
       public function redisAction()
       {
           // Instancier le sérialiseur
           $serializerFactory = new SerializerFactory();
   
           // Options Redis
           // Doit correspondre à la section 'cache' de la config
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600, // Validité en secondes
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'votre_mdp_redis',
           ];
   
           // Instancier l'adaptateur Redis
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // Si la donnée n’est pas encore en cache
               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ée présente
               echo "Data found in cache: ";
           }
   
           // Retourne la donnée (du cache ou fraiche)
           return $cachedData;
       }
   }

   Conseil : Il est recommandé, pour des projets réels, d’enregistrer la connexion cache comme service global.

5. Vérifier

   Rendez-vous sur https://servbay-phalcon-test.local/redis :

   • Première visite : "Data not found in cache, fetching from source...Data stored in cache." + le contenu.
   • Visites ultérieures (avant expiration du cache) : "Data found in cache: " + la valeur.

FAQ (Foire Aux Questions)

• Q : J’obtiens une erreur 404 Not Found en visitant le site ?
  • R : Vérifiez que le « Dossier racine du site » pointe bien sur le dossier public de votre projet Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Contrôlez aussi l’état du serveur web (Caddy ou Nginx) et la résolution locale du domaine.
• Q : Erreur du type « Class 'Phalcon\Mvc\Application' not found » ?
  • R : Cela signifie généralement que l’extension Phalcon n’est pas activée dans la version de PHP utilisée. Dans ServBay, assurez-vous d’avoir coché le module Phalcon pour cette version, puis redémarrez PHP. Voir Activation du module Phalcon avec ServBay.
• Q : Impossible de se connecter à la base de données ?
  • R : Revérifiez les paramètres de connexion (host, username, password, dbname) dans app/config/config.php. Assurez-vous que le service MySQL/MariaDB est bien lancé dans ServBay et que l’utilisateur a les droits sur la base mentionnée, qui doit exister.

Conclusion

Avec ServBay, vous pouvez facilement mettre en place un environnement de développement local hautes performances pour le framework Phalcon. Ce guide vous a présenté la création d’un projet Phalcon, la configuration du serveur web, ainsi que l’intégration de MySQL et Redis. Les nombreux outils et la simplicité d’administration de ServBay rendent la gestion de votre environnement ultra-rapide, vous permettant de vous concentrer sur le code. Nous espérons que ce tutoriel vous permettra de débuter rapidement et efficacement avec Phalcon sur ServBay !