Creare ed Eseguire un Progetto Phalcon

Cos’è Phalcon?

Phalcon è un framework PHP open source e ad alte prestazioni per lo sviluppo web, implementato come estensione C. Questa caratteristica unica consente a Phalcon di avere un consumo di risorse molto basso e una velocità di esecuzione eccezionalmente elevata, superando la maggior parte dei tradizionali framework PHP. Phalcon segue il pattern architetturale MVC (Modello-Vista-Controller) e offre una gamma completa di componenti, inclusi ORM (Object Relational Mapping), motore di template, routing, caching, event manager e altro ancora, facilitando così la rapida creazione di applicazioni web e API potenti e performanti.

Caratteristiche principali e vantaggi di Phalcon

• Prestazioni superiori: Grazie all’esecuzione come estensione C, Phalcon evita l’overhead di parsing e caricamento degli script PHP, offrendo prestazioni a livello nativo.
• Efficienza nelle risorse: Consumo minimo di memoria, ideale per applicazioni con elevati requisiti di velocità e scalabilità.
• Funzionalità complete: Include di default la maggior parte dei componenti fondamentali per lo sviluppo di web app, riducendo la dipendenza da librerie di terze parti.
• Facile da usare: API chiare e coerenti, con documentazione dettagliata, permettono anche ai principianti di apprendere rapidamente.
• Componenti disaccoppiati: Ogni componente è progettato per essere indipendente, consentendo agli sviluppatori di scegliere liberamente quali usare o sostituire in base alle esigenze.
• Sicurezza: Offre numerosi strumenti per la sicurezza, come filtri di input, protezione CSRF e altro.

Phalcon è la scelta ideale per creare web app e API ad alte prestazioni e facilmente scalabili, in particolare per progetti in cui velocità ed efficienza delle risorse sono priorità assolute.

Creare ed eseguire un progetto Phalcon con ServBay

ServBay è un ambiente di sviluppo web locale per macOS che integra molteplici versioni di PHP, database (come MySQL, PostgreSQL, MongoDB, Redis) e server web (Caddy, Nginx, Apache), oltre ad altri strumenti per sviluppatori. Con ServBay puoi facilmente configurare e gestire tutto ciò che serve per sviluppare un'applicazione Phalcon.

In questa guida, ti mostreremo come utilizzare l’ambiente PHP di ServBay per creare un progetto base Phalcon, configurare il server web per renderlo accessibile e integrare database relazionali (MySQL) e NoSQL (Redis).

Prerequisiti

Prima di iniziare, assicurati di avere quanto segue:

1. ServBay installato e avviato: Verifica di aver installato correttamente ServBay su macOS e che l’applicazione sia in esecuzione.
2. La versione PHP richiesta attiva: All’interno di ServBay, assicurati che la versione di PHP che intendi utilizzare sia abilitata.
3. Modulo Phalcon attivato: ServBay include il modulo Phalcon, che però potrebbe non essere attivo di default. Segui la guida su Come abilitare il modulo Phalcon incluso in ServBay per abilitare l’estensione Phalcon nella versione PHP desiderata e riavvia il servizio PHP.
4. Composer disponibile: ServBay include Composer, non serve installarlo separatamente. Verifica di poter usare il comando composer dal terminale.

Versioni di Phalcon e DevTools

Framework e DevTools di Phalcon devono essere compatibili con la versione di PHP in uso. Nella tabella seguente trovi le principali corrispondenze tra versioni PHP ed i pacchetti Phalcon e DevTools raccomandati:

Versione PHP	Versione consigliata di Phalcon	Versione consigliata di Phalcon DevTools	Note
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 (ufficiale)	Compatibilità DevTools ufficiali limitata su PHP 8.x
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repo patchata)	Raccomandato l’uso della versione patchata dalla community

Nota importante: Su PHP 8.x e versioni successive, la compatibilità di DevTools ufficiali non è sempre garantita. È consigliato utilizzare la versione community patchata. La sezione seguente includerà il metodo per installare DevTools patchate tramite Composer.

Creazione di un progetto Phalcon

Suggerimento percorso progetti

Per una migliore gestione, ServBay consiglia di collocare tutti i progetti nella directory predefinita /Applications/ServBay/www. Anche in questo esempio lavoreremo lì.

1. Accedi alla directory dei siti e crea la cartella del progetto

   Apri il terminale, entra nella directory web root di ServBay e crea una cartella (es. servbay-phalcon-app):

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

2. Installa Phalcon DevTools

   DevTools di Phalcon è una suite di strumenti CLI per generare codice, gestire migrazioni e altro. Installa con Composer secondo la versione PHP in uso:

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

     composer require phalcon/devtools:"^3.4"

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

     composer require phalcon/devtools:"~4.1"

   • Per PHP 8.0, 8.1, 8.2, 8.3, 8.4 (DevTools patchati dev-master): Poiché DevTools ufficiali potrebbero non funzionare con PHP 8.x, usa il repository patchato. Modifica/crea un composer.json nella root del progetto:

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

     Poi aggiorna le dipendenze Composer:

     composer update

   Composer creerà la cartella vendor nella root (servbay-phalcon-app). L’eseguibile DevTools si trova in vendor/bin/phalcon.

3. Crea lo scheletro del progetto con DevTools

   Usa ora il comando DevTools appena installato per generare la struttura base. Il codice vero e proprio sarà in una sottocartella dal nome uguale al progetto (default DevTools):

   vendor/bin/phalcon project servbay-phalcon-app

   Verrà creata la sottocartella /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app con la struttura di base di Phalcon.

4. Accedi alla cartella del codice pro progetto

   Muoviti nella nuova sottocartella per tutte le operazioni successive:

   cd servbay-phalcon-app

   Ora sei in /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app.

Configurazione dell’ambiente di progetto

Le principali impostazioni di Phalcon si trovano nel file app/config/config.php. Qui inserirari le info di connessione ai diversi database, i path, ecc.

1. Modifica il file di configurazione

   Apri /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php nel tuo editor preferito. Aggiungi/modifica la sezione di configurazione del database. Il default per MySQL/MariaDB in ServBay è utente root e password vuota, ma per sicurezza si consiglia una password forte. In questo esempio useremo password (modifica secondo il tuo setup). Il database servbay_phalcon_app va creato manualmente.

   return new \Phalcon\Config([
       // ... altre configurazioni ...
       'database' => [
           'adapter' => 'Mysql', // oppure 'Postgres'
           'host' => '127.0.0.1',
           'username' => 'root',
           'password' => 'password', // <-- Inserisci la tua password
           'dbname' => 'servbay_phalcon_app', // <-- Nome db da creare
       ],
       // ... altre configurazioni ...
   ]);

   Importante: Assicurati che il database sia attivo in ServBay e che utente e password combacino. Crea il database servbay_phalcon_app (anche tramite strumenti integrati come phpMyAdmin o Adminer).

Configurazione server web (usando funzionalità "Siti" di ServBay)

Per accedere al progetto via browser, configura in ServBay un nuovo sito che punti all’apposita cartella pubblica.

1. Apri l’app ServBay
2. Vai in “Siti”: Dal menu principale, clicca “Siti”.
3. Aggiungi nuovo sito:
   • Nome: Metti un nome identificativo, es. My First Phalcon Dev Site.
   • Dominio: Scegli un dominio personalizzato, es. servbay-phalcon-test.local (il suffisso .local viene risolto automaticamente in localhost).
   • Tipo di sito: Seleziona PHP.
   • Versione PHP: Scegli la versione PHP in cui hai attivato Phalcon.
   • Root del sito: Qui è fondamentale puntare alla cartella public del progetto: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Salva e applica: ServBay aggiornerà la configurazione (potrebbe essere necessario riavviare il server web, Caddy o Nginx).

Per maggiori dettagli, consulta la guida Aggiungi il primo sito. A configurazione completata, ServBay imposterà automaticamente sia la risoluzione del dominio sia la configurazione del server.

Aggiungi Codice di Esempio

Aggiungiamo del codice semplice per verificare che tutto funzioni.

1. Configura le rotte

   Modifica app/config/routes.php, aggiungendo una rotta per la homepage /:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Definisci la rotta '/' che indirizza a IndexController@indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... altre rotte ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crea un controller

   Modifica (o crea se non esiste) app/controllers/IndexController.php inserendo un semplice metodo indexAction:

   <?php
   namespace App\Controllers; // Controlla il namespace
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Gestisce la richiesta su '/'
       public function indexAction()
       {
           // Restituisce una semplice risposta di testo
           return 'Hello ServBay!';
       }
   }

Visita il Sito

Salva tutti i file, controlla che ServBay sia in esecuzione. Dal browser vai all'indirizzo scelto:

https://servbay-phalcon-test.local

Se tutto è stato configurato correttamente, dovresti vedere la scritta Hello ServBay!.

Integrazione Database

Phalcon offre un livello di astrazione per i database e un ORM potente. ServBay integra diversi motori; puoi connetterli facilmente ai tuoi progetti. Qui mostriamo esempi per MySQL (relazionale) e Redis (NoSQL).

Esempio Relazionale: MySQL

Vediamo come collegarsi a MySQL di ServBay e fare semplici operazioni.

1. Crea la struttura del database (migrazione)

   Phalcon DevTools supporta le migrazioni per la gestione della struttura del database.

   • Genera il file di migrazione: Dalla cartella codice (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app):

     vendor/bin/phalcon migration generate

     Questo crea un file nella directory migrations (nome tipo YYYYMMDDHHMMSS_MigrationName.php).

   • Modifica il file di migrazione: Aprilo e aggiungi una definizione di tabella users:

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // Assicurati che il nome classe corrisponda al file
     {
         /**
          * Esegui la migrazione
          */
         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',
                 ],
             ]);
         }
     
         /**
          * Reverse migration
          */
         public function down()
         {
             // Facoltativo: implementa logica di rollback, es. drop table
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: Assicurati che il nome della classe (es. UsersMigration_100) corrisponda al nome file.

   • Esegui la migrazione: Da terminale esegui:

     vendor/bin/phalcon migration run

     Se dovessi ricevere errori di connessione, controlla la configurazione DB in app/config/config.php e assicurati che MySQL/MariaDB in ServBay sia attivo.

2. Configura la connessione al DB (già fatto sopra)

   In app/config/config.php la sezione 'database' deve puntare a MySQL/MariaDB su ServBay (host 127.0.0.1, porta 3306, utente root, password secondo la tua configurazione).

3. Aggiungi rotte di esempio

   Modifica app/config/routes.php aggiungendo rotte per inserimento e query utenti:

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // Rotta per inserimento nuovo utente
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // Rotta per elenco utenti
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. Implementa operazioni DB nel controller

   Modifica app/controllers/IndexController.php, aggiungi i metodi mysqlAddAction e mysqlAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Adapter MySQL
   use Phalcon\Db\Enum; // Costanti per fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Inserisce un nuovo utente
       public function mysqlAddAction()
       {
           // Connessione DB (in produzione meglio usare il Service Container)
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Inserisci la tua password database
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           // Inserimento
           $success = $connection->insert(
               'users',
               ['ServBay Demo User', '[email protected]'],
               ['name', 'email']
           );
   
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Lista utenti in formato JSON
       public function mysqlAction()
       {
            $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- Inserisci la tua password database
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   Nota: Nella pratica, la connessione va configurata come servizio e usata tramite Dependency Injection.

5. Prova le rotte

   • Visita https://servbay-phalcon-test.local/mysql-add – se tutto ok, vedrai "User added successfully."
   • Poi visita https://servbay-phalcon-test.local/mysql – il browser mostrerà i dati utenti in formato JSON.

Esempio NoSQL: Redis

Vediamo come usare Redis (già incluso in ServBay) per caching.

1. Estensione Redis

   Le versioni PHP di ServBay includono già l’estensione Redis. Assicurati solo che sia attiva per la versione in uso.

2. Configura la connessione Redis

   In app/config/config.php aggiungi la sezione per Redis. Il servizio Redis in ServBay opera di default su 127.0.0.1:6379.

   return new \Phalcon\Config([
       // ... altre configurazioni ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Database Redis, default 0
           'persistent' => false,
           'auth' => null, // Inserisci qui la password se impostata
       ],
       // ... altre configurazioni ...
   ]);

3. Aggiungi rotta di esempio

   In app/config/routes.php, aggiungi una rotta /redis per il test cache:

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

4. Usa Redis nel controller

   Modifica app/controllers/IndexController.php, aggiungi il metodo redisAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Adapter Redis
   use Phalcon\Storage\SerializerFactory; // Serializer
   
   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);
       }
   
       // Esempio cache Redis
       public function redisAction()
       {
           // Istanza serializer
           $serializerFactory = new SerializerFactory();
   
           // Config cache Redis
           // Deve rispecchiare la sezione 'cache' in config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
               // 'auth'           => 'your_redis_password'
           ];
   
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               // Se il dato non è in 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 {
               // Presa dal cache
               echo "Data found in cache: ";
           }
   
           // Restituisci il dato
           return $cachedData;
       }
   }

   Nota: Generalmente la gestione cache viene registrata come servizio per una migliore riusabilità.

5. Prova l’esempio

   Visita https://servbay-phalcon-test.local/redis:

   • Alla prima visita vedrai "Data not found in cache, fetching from source...Data stored in cache." seguito da "Data fetched from source: Hello Redis from ServBay!".
   • Nei richiami successivi (fino alla scadenza del cache), vedrai "Data found in cache: " e "Data fetched from source: Hello Redis from ServBay!", a dimostrazione dell’utilizzo dei dati da Redis.

FAQ (Domande frequenti)

• Domanda: ricevo errore 404 Not Found accedendo al sito
  • Risposta: Assicurati che la root del sito in ServBay punti esattamente alla cartella public del tuo progetto Phalcon (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Verifica che il server web (Caddy o Nginx) sia avviato e la risoluzione DNS locale funzioni.
• Domanda: errore “Class 'Phalcon\Mvc\Application' not found” o simili
  • Risposta: Il modulo Phalcon non è attivo nella versione PHP selezionata. Riapri ServBay, attiva il modulo Phalcon per la versione PHP del progetto e riavvia il PHP service. Consulta come abilitare Phalcon in ServBay.
• Domanda: problemi di connessione al database
  • Risposta: Verifica i parametri di connessione in app/config/config.php (host, utente, password, nome database). Assicurati che il database sia in esecuzione da ServBay e che l’utente abbia permessi di accesso; crea il database se necessario.

Conclusioni

Grazie a ServBay puoi configurare facilmente un ambiente locale ad alte prestazioni per sviluppare app con Phalcon. Questa guida ti ha illustrato come generare la struttura base del progetto, impostare il server web e integrare database MySQL e Redis. I numerosi software e l’interfaccia intuitiva di ServBay semplificano notevolmente la gestione dell’ambiente locale, permettendoti di concentrarti sullo sviluppo del tuo progetto Phalcon. Speriamo che questa guida ti sia utile per iniziare subito con un ambiente produttivo e performante!