Creazione e Avvio di un Progetto Phalcon

Cos’è Phalcon?

Phalcon è un framework PHP open source ad alte prestazioni, implementato come estensione C. Questa architettura unica garantisce un consumo minimo di risorse e velocità di esecuzione notevolmente superiore ai framework PHP tradizionali. Phalcon segue il modello MVC (Model-View-Controller) e mette a disposizione una suite completa di componenti, tra cui ORM (mappatura oggetti-relazionale), motore di template, routing, cache, gestore eventi e altro ancora, fornendo agli sviluppatori gli strumenti per costruire applicazioni web e API potenti e performanti con rapidità.

Caratteristiche e Vantaggi Principali di Phalcon

• Performance Eccellente: Grazie all’esecuzione come estensione C, Phalcon elimina le overhead di parsing e caricamento degli script PHP, offrendo prestazioni a livello nativo.
• Alta Efficienza delle Risorse: Consumo di memoria estremamente ridotto, ideale per applicazioni con elevati requisiti di scalabilità e performance.
• Funzionalità Completa: Include la maggior parte dei componenti necessari per lo sviluppo di applicazioni web, minimizzando la dipendenza da librerie di terze parti.
• Facilità d’Uso: API chiara e coerente, documentazione dettagliata; anche i nuovi utenti possono imparare rapidamente.
• Componenti Modulare: Ogni componente è progettato in modo indipendente e può essere sostituito o usato a discrezione del progetto.
• Sicurezza: Offre tool per la sicurezza come filtri d’input e protezione CSRF.

Phalcon è la soluzione ideale per applicazioni web e API che richiedono velocità e efficienza delle risorse.

Creare e Avviare un Progetto Phalcon con ServBay

ServBay è un ambiente di sviluppo locale progettato per macOS, che integra molteplici versioni di PHP, database (MySQL, PostgreSQL, MongoDB, Redis), server web (Caddy, Nginx, Apache) e altri tool. Con ServBay puoi configurare facilmente l’ambiente di esecuzione necessario per un progetto Phalcon.

Questa guida ti guida nella creazione di un progetto Phalcon di base usando ServBay, nella configurazione del server web per l’accessibilità del progetto e mostra come integrare database relazionali (MySQL) e NoSQL (Redis).

Prerequisiti

Prima di iniziare, verifica di avere:

1. ServBay installato e in esecuzione: ServBay deve essere correttamente installato e avviato su macOS.
2. Versione PHP richiesta abilitata: Verifica che la versione di PHP che intendi usare sia abilitata in ServBay.
3. Modulo Phalcon abilitato: ServBay include Phalcon, ma potrebbe essere disabilitato di default. Segui la guida Come abilitare il modulo Phalcon di ServBay per attivare l’estensione per la versione PHP desiderata e riavvia il servizio PHP.
4. Composer disponibile: ServBay include Composer, quindi non è necessario installarlo separatamente. Assicurati che il comando composer sia utilizzabile direttamente dal terminale.

Versioni di Phalcon e DevTools Compatibili

Le versioni di Phalcon e dei DevTools devono essere compatibili con la versione di PHP utilizzata. Ecco una tabella che mostra le principali corrispondenze consigliate:

Versione PHP	Versione Phalcon consigliata	Versione DevTools consigliata	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 (oppure 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (ufficiale)	DevTools ufficiali potrebbero avere problemi di compatibilità.
PHP 8.3, 8.4	Phalcon 5.x	dev-master (repository patchato)	Consigliato l’uso della versione patchata mantenuta dalla community.

Nota Importante: Per PHP 8.x e versioni successive, i DevTools ufficiali potrebbero non funzionare correttamente. Si raccomanda di usare la versione patchata della community, come illustrato nei prossimi passaggi.

Creazione di un Progetto Phalcon

Percorso consigliato per i siti

Per una migliore organizzazione, ServBay consiglia di mantenere tutti i progetti nella directory radice predefinita dei siti, /Applications/ServBay/www. In questo esempio useremo tale percorso.

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

   Apri il terminale, spostati nella root dei siti ServBay e crea una nuova cartella per il tuo progetto (ad esempio servbay-phalcon-app):

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

2. Installa Phalcon DevTools

   Phalcon DevTools è un set di tool CLI che facilita generazione di codice, creazione dello scheletro del progetto, migrazioni database, etc. Usa Composer per installarlo (il comando dipende dalla versione PHP):

   • 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 patchata dev-master): Siccome i DevTools ufficiali potrebbero non supportare PHP 8.x, occorre usare una versione patchata della community. Crea o modifica il file composer.json nella root del progetto (/Applications/ServBay/www/servbay-phalcon-app) e aggiungi la configurazione del repository patchato:

     {
        "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 esegui:

     composer update

   Composer crea una directory vendor con il file eseguibile DevTools in vendor/bin/phalcon.

3. Crea lo scheletro del progetto con DevTools

   Ora, usa DevTools per generare la struttura di base del progetto. Per convenzione, il codice viene inserito in una sottocartella con lo stesso nome del progetto:

   vendor/bin/phalcon project servbay-phalcon-app

   Questo comando crea un nuovo sottodirectory /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app che contiene una struttura completa del progetto Phalcon.

4. Spostati nella directory del codice

   Entra nella directory appena creata dove si continueranno i passaggi successivi:

   cd servbay-phalcon-app

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

Configurazione dell’Ambiente di Progetto

La configurazione principale si trova nel file app/config/config.php. Qui puoi definire le connessioni al database, percorsi dell’applicazione e altri parametri essenziali.

1. Modifica il file di configurazione

   Apri /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php nel tuo editor preferito e configura i parametri del database. Di default, MySQL/MariaDB in ServBay usa root come utente e password vuota, ma per sicurezza è preferibile impostare una password robusta. Sostituisci password e servbay_phalcon_app con i dati reali:

   return new \Phalcon\Config([
       // ... altre configurazioni ...
       'database' => [
           'adapter' => 'Mysql', // oppure 'Postgres'
           'host' => '127.0.0.1',
           'username' => 'root', // Utente predefinito in ServBay
           'password' => 'password', // <--- Da modificare con la tua password
           'dbname' => 'servbay_phalcon_app', // <--- Da modificare con il nome del tuo database
       ],
       // ... altre configurazioni ...
   ]);

   Importante: Assicurati che il servizio database (MySQL/MariaDB) sia avviato in ServBay e che utente, password e nome database corrispondano. Il database servbay_phalcon_app va creato manualmente tramite adminer, phpMyAdmin o simili.

Configurazione del Server Web (tramite la funzione “Sito” di ServBay)

Per accedere al progetto via browser, configura un virtual host usando la funzione Sito di ServBay e punta la root web sulla directory corretta.

1. Avvia ServBay
2. Entra nelle impostazioni “Sito”: Nell’interfaccia principale seleziona “Siti”.
3. Aggiungi un nuovo sito:
   • Nome: Usa un nome descrittivo, ad esempio My First Phalcon Dev Site.
   • Dominio: Inserisci un dominio locale come servbay-phalcon-test.local, ServBay gestirà la risoluzione.
   • Tipo di sito: Scegli PHP.
   • Versione PHP: Seleziona quella con Phalcon abilitato.
   • Root sito: La root web deve puntare alla directory public del progetto, ovvero: /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public.
4. Salva: Salva la configurazione. ServBay gestisce automaticamente la risoluzione del dominio e la configurazione del web server (Caddy o Nginx).

Per dettagli vedi Aggiunta del primo sito.

Aggiunta di Codice di Esempio

Aggiungiamo ora del codice per confermare che il progetto si avvia correttamente.

1. Configura la route principale

   Modifica /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php e aggiungi una semplice route per la homepage (/):

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // Definisci la route di default che mappa '/' su IndexController@indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... altre route eventuali ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. Crea il controller

   Modifica o crea /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php con il metodo indexAction:

   <?php
   namespace App\Controllers; // Assicurati che il namespace sia corretto
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // Gestisce la ruta '/'
       public function indexAction()
       {
           // Restituisce una semplice stringa di risposta
           return 'Hello ServBay!';
       }
   }

Accesso al Sito

Dopo aver salvato i file, assicurati che ServBay sia attivo. Apri il browser e visita:

https://servbay-phalcon-test.local

Se tutto è configurato correttamente, vedrai il messaggio Hello ServBay!.

Integrazione del Database

Phalcon include un potente layer di astrazione database e ORM. ServBay integra vari database per una facile connessione. Ecco come integrarlo con MySQL e Redis.

Esempio Database Relazionale: MySQL

Vediamo come utilizzare l’adattatore database Phalcon per MySQL in ServBay, con operazioni di inserimento e query.

1. Crea la struttura database (Migrazioni)

   Phalcon DevTools supporta le migrazioni per il controllo delle versioni dello schema DB.

   • Genera un file di migrazione: Nella directory del codice esegui:

     vendor/bin/phalcon migration generate

     Otterrai un nuovo file in migrations, es. YYYYMMDDHHMMSS_MigrationName.php.

   • Modifica il file: Inserisci la definizione della tabella users nel metodo morph:

     <?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
     {
         /**
          * Esegue la migrazione
          *
          * @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',
                 ],
             ]);
         }
     
         /**
          * Annulla la migrazione
          *
          * @return void
          */
         public function down()
         {
             // Opzionale: logica di rollback, es. eliminazione tabella
             // $this->getConnection()->dropTable('users');
         }
     }

     Nota: La classe deve corrispondere al nome del file.

   • Esegui la migrazione: Nella directory esegui:

     vendor/bin/phalcon migration run

     Se hai errori di connessione, verifica il config del database e che il servizio in ServBay sia avviato.

2. Configura la connessione al database

   La configurazione l’hai già impostata prima nel file config.php.

3. Aggiungi le route di esempio

   Modifica app/config/routes.php, aggiungi route per inserimento e interrogazione utenti:

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

4. Implementa le operazioni DB nel controller

   Modifica app/controllers/IndexController.php e aggiungi i metodi per operare con il DB:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // Importa adattatore MySQL
   use Phalcon\Db\Enum; // Per costanti fetchAll
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // Inserimento utente
       public function mysqlAddAction()
       {
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <--- Modifica con password reale
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4',
           ]);
   
           $success = $connection->insert(
               'users', // Tabella
               ['ServBay Demo User', 'demo@servbay.test'], // Valori
               ['name', 'email'] // Colonne
           );
   
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // Query utenti
       public function mysqlAction()
       {
            $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <--- Modifica con password reale
               '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: In produzione, è meglio gestire le connessioni tramite il service container e l’injection.

5. Accesso

   • Visita https://servbay-phalcon-test.local/mysql-add per inserire un utente.
   • Poi visita https://servbay-phalcon-test.local/mysql per vedere la lista utenti in JSON.

Esempio NoSQL: Redis

Ora vediamo come usare Redis come cache con Phalcon e ServBay.

1. Assicurati che l’estensione Redis sia installata

   ServBay include comunemente l’estensione Redis. Basta controllare che sia abilitata per la versione PHP usata nel progetto.

2. Configura la connessione Redis

   Nel file app/config/config.php aggiungi la configurazione Redis. ServBay usa tipicamente 127.0.0.1:6379:

   return new \Phalcon\Config([
       // ... altre configurazioni ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0,
           'persistent' => false,
           'auth' => null,
       ],
       // ... altre configurazioni ...
   ]);

3. Aggiungi la route di esempio

   Modifica app/config/routes.php e aggiungi la route /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 per dimostrare uso 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 e aggiungi redisAction:

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // Importa adattatore Redis
   use Phalcon\Storage\SerializerFactory; // Importa 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 uso cache Redis
       public function redisAction()
       {
           $serializerFactory = new SerializerFactory();
   
           // Configurazione cache Redis, coerente con config.php
           $options = [
               'defaultSerializer' => 'Json',
               'lifetime'          => 3600,
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0,
           ];
   
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey);
   
           if ($cachedData === null) {
               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 {
               echo "Data found in cache: ";
           }
   
           return $cachedData;
       }
   }

   Nota: In produzione si consiglia di gestire la cache via servizi/injection.

5. Accesso

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

   • Alla prima visita vedrai "Data not found in cache, fetching from source...Data stored in cache." e "Data fetched from source: Hello Redis from ServBay!".
   • Visitando nuovamente, vedrai "Data found in cache: " e "Data fetched from source: Hello Redis from ServBay!", segno che i dati arrivano da Redis.

FAQ

• Q: Ottengo un errore 404 Not Found accedendo al sito.
  • A: Verifica che la “Root sito” nelle impostazioni ServBay punti alla directory public (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public). Controlla che il web server sia avviato e che il dominio locale sia risolto correttamente.
• Q: Errore “Phalcon module not found” (es. Class 'Phalcon\Mvc\Application' not found).
  • A: Solitamente l’estensione Phalcon non è abilitata sulla versione PHP usata. Riattivala dall’interfaccia ServBay e riavvia PHP. Consulta Come abilitare il modulo Phalcon di ServBay.
• Q: Fallimento connessione al database.
  • A: Controlla che i parametri nel config sono corretti (host, utente, password, nome DB), che il servizio DB sia avviato e che l’utente abbia i permessi necessari.

Conclusione

Con ServBay, configurare un ambiente locale Phalcon ad alte prestazioni è semplice e veloce. Questa guida ti ha mostrato come creare la struttura di un progetto, configurare il server web e integrare MySQL e Redis. Gli strumenti e l’interfaccia di ServBay semplificano la gestione ambientale, permettendoti di concentrarti sullo sviluppo dell’applicazione Phalcon vera e propria. Buon lavoro con ServBay e Phalcon!