Creare ed Eseguire un Progetto CakePHP con ServBay

ServBay è un ambiente di sviluppo Web locale progettato specificamente per macOS, che integra ambienti multi-linguaggio come PHP, Node.js, Python, Go e Java, oltre a servizi di database quali MySQL, PostgreSQL, MongoDB, Redis e altri, supportando Caddy o Nginx come server Web. Offre una piattaforma di sviluppo pratica ed efficiente che permette agli sviluppatori di configurare e gestire facilmente progetti locali.

Questo articolo ti guiderà su come creare, configurare ed eseguire un progetto CakePHP all'interno dell’ambiente ServBay. CakePHP è un noto framework PHP per lo sviluppo Web che segue il modello MVC (Model-View-Controller), riconosciuto per la rapidità nello sviluppo, il potente ORM e le funzionalità di sicurezza integrate. Grazie alla praticità di ServBay, potrai iniziare rapidamente a sviluppare con CakePHP.

Cos'è CakePHP?

CakePHP è un framework di sviluppo per applicazioni Web PHP open source che fornisce una struttura di base per lo sviluppo rapido e strutturato di applicazioni Web, senza sacrificare la flessibilità. Segue il principio della "convention over configuration", semplificando molte attività di sviluppo comuni.

Principali Caratteristiche e Vantaggi di CakePHP

• Basato su architettura MVC: Struttura del codice chiara, facile da mantenere ed estendere.
• Sviluppo rapido: Offre strumenti a riga di comando (Bake) per generare codice e velocizzare il workflow.
• Potente ORM (Object-Relational Mapping): Semplifica l'interazione con il database e supporta diversi sistemi di database.
• Sicurezza integrata: Funzionalità pronte all’uso per la protezione CSRF, prevenzione SQL injection, validazione dell’input e altro ancora.
• Motore di template flessibile: Supporta varie tecnologie per il livello di visualizzazione.
• Comunità attiva e ampia disponibilità di plugin: Supporto facilmente reperibile e funzionalità estensibili.
• Documentazione dettagliata: Guide e API di riferimento complete.

CakePHP è adatto per applicazioni Web di ogni dimensione, dalle semplici API ai sistemi enterprise complessi.

Configurare un Ambiente di Sviluppo CakePHP con ServBay

ServBay fornisce un ambiente integrato ideale per lo sviluppo con CakePHP, tra cui:

• Interprete PHP preinstallato con le estensioni più comuni.
• Composer, il gestore dei pacchetti già installato.
• Server Web facilmente configurabile (Caddy/Nginx).
• Servizi di database integrati (MySQL, PostgreSQL, Redis, ecc.).

Grazie a ServBay, non dovrai più occuparti manualmente dell’installazione e configurazione di questi componenti.

Prerequisiti

Prima di iniziare, assicurati di aver completato le seguenti operazioni:

1. Installa ServBay: Scarica e installa correttamente ServBay su macOS.
2. Avvia i servizi ServBay: Avvia l’applicazione ServBay e assicurati che i pacchetti desiderati (ad es. PHP, il database scelto come MySQL o PostgreSQL e servizi cache come Redis o Memcached) siano attivi. Puoi gestire questi servizi nella scheda “Pacchetti” del pannello di controllo di ServBay.
3. Familiarità con le operazioni di base di ServBay: Sapere come aggiungere e configurare un sito Web in ServBay. Se sei alle prime armi, consulta prima la Guida Base all'Uso di ServBay.

Creare un Progetto CakePHP

Si consiglia di archiviare tutti i file dei progetti Web nella directory /Applications/ServBay/www, così che ServBay possa riconoscere e gestire automaticamente i tuoi siti.

1. Apri il terminale

   Avvia l’app Terminale di macOS.

2. Naviga nella directory root dei siti ServBay

   Spostati nella cartella raccomandata per i siti Web di ServBay:

   cd /Applications/ServBay/www

3. Crea la directory del progetto

   Crea una sottocartella per il tuo progetto CakePHP. Useremo servbay-cakephp-app come nome di esempio:

   mkdir servbay-cakephp-app
   cd servbay-cakephp-app

4. Crea il progetto CakePHP con Composer

   Composer è già preinstallato tramite ServBay. All’interno della directory del progetto, esegui:

   composer create-project --prefer-dist cakephp/app .

   Questo comando scarica e installa nell’attuale directory (.) l’ultima versione stabile di CakePHP e tutte le sue dipendenze.

5. Installa il driver ORM (per PostgreSQL)

   Se desideri usare PostgreSQL, installa il driver ORM aggiuntivo:

   composer require cakephp/orm-pgsql

   Per MySQL, il driver è già incluso tra le dipendenze core di CakePHP.

Configurazione Iniziale

Dopo aver creato il progetto, procedi con le impostazioni di base, in particolare la configurazione del database.

1. Configura le variabili d’ambiente e la connessione al database

   La configurazione locale di CakePHP si trova principalmente nel file config/app_local.php. Modifica tale file, cerca la sezione Datasources e inserisci i dettagli della connessione al database. Per ServBay, l’utente di default è root, la password password.

   Esempio di configurazione MySQL:

   // config/app_local.php
   'Datasources' => [
       'default' => [
           'className' => \Cake\Database\Connection::class,
           'driver' => \Cake\Database\Driver\Mysql::class, // oppure \Cake\Database\Driver\Postgres::class per PostgreSQL
           'persistent' => false,
           'host' => '127.0.0.1', // indirizzo server database, di default locale in ServBay
           //'port' => '3306', // porta predefinita MySQL 3306, PostgreSQL 5432
           'username' => 'root', // username predefinito ServBay
           'password' => 'password', // password ServBay
           'database' => 'servbay_cakephp_app', // nome database da creare
           'encoding' => 'utf8mb4',
           'timezone' => 'UTC',
           'flags' => [],
           'cacheMetadata' => true,
           'log' => false,
   
           /**
            * Attiva il quoting degli identificatori se usi nomi come "user" per le tabelle.
            * Se utilizzi nomi come "cake" puoi lasciare false.
            * Se non sei sicuro, lascia true.
            */
           'quoteIdentifiers' => false,
   
           /**
            * Attuali limitazioni includono:
            * - La maggior parte dei driver non supporta l'impostazione dei livelli di isolamento tramite opzioni PDO.
            *   L’uso potrebbe restituire errori.
            * - Non tutti i driver permettono di impostare il charset tramite opzioni PDO.
            *   L’uso potrebbe restituire errori.
            * - Le opzioni PDO non sono supportate dai driver impacchettati come Postgres per CakePHP.
            *   Per Postgres, imposta solo "encoding".
            */
           'options' => [],
   
           //'url' => env('DATABASE_URL', null), // se usi la variabile d’ambiente DATABASE_URL, abilita questa riga
       ],
   ],

   Modifica driver e (se necessario) port in base al tipo di database scelto (MySQL o PostgreSQL). Verifica che il nome del database coincida con quello che andrai a creare.

Configurare il Server Web (Creare un Sito su ServBay)

Per poter accedere al progetto CakePHP dal browser, configura un nuovo sito in ServBay che punti alla directory appropriata del progetto.

1. Apri il pannello di controllo di ServBay

   Clicca sull’icona di ServBay per aprire il pannello.

2. Naviga alla scheda "Siti"

   Per ServBay in versione italiana potrebbe chiamarsi “Siti”; nell’elenco di navigazione a sinistra.

3. Aggiungi un nuovo sito

   Clicca sul pulsante + in fondo alla schermata per aggiungere un nuovo sito. Compila i campi seguenti:

   • Nome: Dai un nome riconoscibile, ad es. My CakePHP Dev Site
   • Dominio: Scegli un dominio locale, es. servbay-cakephp-test.local. ServBay lo punterà automaticamente al locale.
   • Tipo di sito: Scegli PHP.
   • Versione PHP: Seleziona una versione compatibile col tuo CakePHP (ad esempio CakePHP 4+ richiede almeno PHP 7.4, CakePHP 5+ almeno PHP 8.1; consigliato ad es. 8.3).
   • Document Root: Importante! La document root NON è la directory principale del progetto, ma la sottocartella interna webroot. Imposta su /Applications/ServBay/www/servbay-cakephp-app/webroot (sostituisci servbay-cakephp-app col nome effettivo della tua cartella progetto).

4. Salva e applica le modifiche

   Dopo aver compilato il form, clicca su “Salva”. ServBay ti chiederà se vuoi applicare le modifiche: conferma. Il server Web (Caddy o Nginx) sarà configurato automaticamente per rispondere a servbay-cakephp-test.local indirizzando le richieste alla cartella webroot del tuo progetto.

Per istruzioni passo-passo consulta la documentazione ServBay alla sezione Aggiungi il primo sito.

Verificare la Configurazione di Base

Ora dovresti poter testare il tuo sito dal browser.

Apri il browser e visita il dominio impostato, ad esempio https://servbay-cakephp-test.local.

Se tutto è stato configurato correttamente, vedrai la pagina di benvenuto di CakePHP. Questo indica che l’ambiente PHP, il server Web e la configurazione dei siti su ServBay funzionano perfettamente.

Integrazione di Database e Servizi Cache

CakePHP mette a disposizione un potente ORM e un layer astratto per la cache, facilitando l’integrazione con i database e i servizi cache forniti da ServBay.

Esempio di Database Relazionale (MySQL / PostgreSQL)

Vediamo come usare l’ORM di CakePHP per collegarsi al database MySQL o PostgreSQL di ServBay, creare la tabella users e operare su di essa.

1. Crea il database in ServBay

   Prima delle migrazioni, crea un nuovo database usando lo strumento gestione DB fornito da ServBay (phpMyAdmin per MySQL/MariaDB, pgAdmin per PostgreSQL, Navicat/DBeaver ecc.). Collegati a 127.0.0.1 con utente root e password password, poi crea un database chiamato servbay_cakephp_app.

2. Crea il file Model ORM

   CakePHP necessita di un file Model per rappresentare la tabella. Crea il file UsersTable.php per la tabella users.

   Salva il codice seguente in src/Model/Table/UsersTable.php:

   <?php
   namespace App\Model\Table;
   
   use Cake\ORM\Table;
   use Cake\Validation\Validator; // Se vuoi definire le regole di validazione
   
   class UsersTable extends Table
   {
       /**
        * Initialize method
        *
        * @param array $config The configuration for the Table.
        * @return void
        */
       public function initialize(array $config): void
       {
           parent::initialize($config);
   
           $this->setTable('users'); // Specifica il nome della tabella
           $this->setDisplayField('name'); // Campo visualizzato di default
           $this->setPrimaryKey('id'); // Chiave primaria
   
           // Se vuoi abilitare i timestamp automatici:
           // $this->addBehavior('Timestamp');
       }
   
       /**
        * Regole di validazione di default
        *
        * @param \Cake\Validation\Validator $validator Validator instance.
        * @return \Cake\Validation\Validator
        */
       public function validationDefault(Validator $validator): Validator
       {
           $validator
               ->scalar('name')
               ->maxLength('name', 255)
               ->requirePresence('name', 'create')
               ->notEmptyString('name');
   
           $validator
               ->email('email')
               ->requirePresence('email', 'create')
               ->notEmptyString('email')
               ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // Email unica
   
           return $validator;
       }
   }

3. Genera file di migrazione con Bake

   CakePHP consiglia di gestire la struttura DB tramite migrazioni. Dalla radice del progetto (/Applications/ServBay/www/servbay-cakephp-app) esegui:

   bin/cake bake migration CreateUsers name:string email:string:unique

   Questo comando crea un file di migrazione per la tabella users con i campi name (stringa) e email (stringa unica).

4. Esegui la migrazione database

   Avvia la migrazione che crea fisicamente la tabella nel database:

   bin/cake migrations migrate

   Al termine della migrazione, la tabella users sarà disponibile nel tuo database.

5. Assicurati della configurazione database

   Controlla che config/app_local.php (se non già fatto) riporti i parametri corretti nella sezione Datasources.default.

   • Esempio configurazione MySQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Mysql::class,
             'host' => '127.0.0.1',
             'username' => 'root',
             'password' => 'password',
             'database' => 'servbay_cakephp_app',
             // ... altre opzioni
         ],
     ],

   • Esempio configurazione PostgreSQL:

     'Datasources' => [
         'default' => [
             'className' => \Cake\Database\Connection::class,
             'driver' => \Cake\Database\Driver\Postgres::class,
             'host' => '127.0.0.1',
             // 'port' => '5432', // Porta di default
             'username' => 'root', // Utente default ServBay
             'password' => 'password', // Password default ServBay
             'database' => 'servbay_cakephp_app',
             // ... altre opzioni
         ],
     ],

6. Aggiungi route e metodi controller di esempio

   Modifica config/routes.php per aggiungere rote dedicate ad inserimento e lettura utenti:

   // config/routes.php
   use Cake\Routing\RouteBuilder;
   use Cake\Routing\Router;
   use Cake\Routing\Route\DashedRoute;
   
   Router::defaultRouteClass(DashedRoute::class);
   
   Router::scope('/', function (RouteBuilder $routes) {
       // ... altre route
       $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']);
   
       // Route per esempio database
       $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']);
       $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']);
   
       // ... altre route
       $routes->fallbacks(DashedRoute::class);
   });

   Modifica src/Controller/PagesController.php per inserire i metodi relativi:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\ORM\TableRegistry;
   use Cake\Datasource\Exception\RecordNotFoundException; // Gestione eccezioni
   
   class PagesController extends AppController
   {
       /**
        * Visualizza una vista
        *
        * @param array ...$path Segmenti del percorso.
        * @return \Cake\Http\Response|null
        */
       public function display(...$path): ?Response
       {
           // ... Metodo display di default
           return new Response(['body' => 'Hello ServBay! Questa è la pagina di default.']);
       }
   
       /**
        * Esempio DB: Aggiungi Utente
        */
       public function dbAddUser(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users');
   
           // Crea nuovo entity utente
           $user = $usersTable->newEntity([
               'name' => 'ServBay Demo User',
               'email' => '[email protected]'
           ]);
   
           // Salva nel database
           if ($usersTable->save($user)) {
               return new Response(['body' => 'Utente aggiunto con successo! User ID: ' . $user->id]);
           } else {
               // Errore di validazione o altro
               $errors = $user->getErrors();
               return new Response(['body' => 'Errore nell\'aggiunta dell\'utente. Errori: ' . json_encode($errors)]);
           }
       }
   
       /**
        * Esempio DB: Lista utenti
        */
       public function dbListUsers(): Response
       {
           $usersTable = TableRegistry::getTableLocator()->get('Users');
   
           // Trova tutti gli utenti
           $users = $usersTable->find()->all();
   
           // Output JSON
           return new Response(['body' => json_encode($users->toArray())]);
       }
   }

7. Prova gli endpoint di esempio

   Apri il browser:

   • Vai su https://servbay-cakephp-test.local/db-add-user per aggiungere un utente. Vedrai un messaggio di conferma.
   • Vai su https://servbay-cakephp-test.local/db-list-users per visualizzare tutti gli utenti (incluso quello appena creato).

Così facendo, collegherai con successo il progetto CakePHP al database relazionale di ServBay ed eseguirai operazioni ORM di base.

Esempio Servizi Cache (Memcached / Redis)

CakePHP offre una API di cache unificata che permette lo switch rapido tra diversi motori, es. Memcached o Redis. ServBay preinstalla entrambe le estensioni PHP e offre i relativi servizi.

Prima di proseguire, verifica che nella scheda "Pacchetti" di ServBay sia attivo il servizio Memcached o Redis.

1. Configura la connessione cache

   Modifica il file config/app_local.php, sezione Cache.

   • Esempio configurazione Memcached:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\MemcachedEngine::class,
             'servers' => ['127.0.0.1:11211'],
             'prefix' => 'servbay_cakephp_',
         ],
         // ... altre configurazioni cache
     ],

   • Esempio configurazione Redis:

     // config/app_local.php
     'Cache' => [
         'default' => [
             'className' => \Cake\Cache\Engine\RedisEngine::class,
             'host' => '127.0.0.1',
             'port' => 6379,
             'password' => null, // Inserisci se necessario
             'database' => 0,
             'prefix' => 'servbay_cakephp_',
         ],
         // ... altre configurazioni cache
     ],

   Configura in base al servizio che desideri usare.

2. Aggiungi route e metodi controller di esempio

   Modifica config/routes.php aggiungendo le rotte cache:

   // config/routes.php
   // ... altre rotte
   $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']);
   $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']);
   // ... altre rotte

   In src/Controller/PagesController.php aggiungi i metodi:

   <?php
   namespace App\Controller;
   
   use Cake\Http\Response;
   use Cake\Cache\Cache;
   // ... altri use
   
   class PagesController extends AppController
   {
       // ... altri metodi (display, dbAddUser, dbListUsers)
   
       /**
        * Esempio cache: Memcached
        */
       public function cacheMemcached(): Response
       {
           // Controlla che in app_local.php 'default' usi MemcachedEngine
   
           $cacheKey = 'servbay_memcached_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Miss cache
               $responseBody = 'Cache miss! Scrittura "Hello Memcached!" nella cache.';
               $dataToCache = 'Hello Memcached!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Hit cache
               $responseBody = 'Cache hit! Dato letto dalla cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   
       /**
        * Esempio cache: Redis
        */
       public function cacheRedis(): Response
       {
            // Controlla che in app_local.php 'default' usi RedisEngine
   
           $cacheKey = 'servbay_redis_test_key';
           $cachedData = Cache::read($cacheKey);
   
           $responseBody = '';
   
           if ($cachedData === false) {
               // Miss cache
               $responseBody = 'Cache miss! Scrittura "Hello Redis!" nella cache.';
               $dataToCache = 'Hello Redis!';
               Cache::write($cacheKey, $dataToCache, 'default');
           } else {
               // Hit cache
               $responseBody = 'Cache hit! Dato letto dalla cache: ' . $cachedData;
           }
   
           return new Response(['body' => $responseBody]);
       }
   }

3. Verifica gli esempi Cache

   Apri il browser:

   • Se hai configurato Memcached, visita https://servbay-cakephp-test.local/cache-memcached. Alla prima chiamata leggerai “Cache miss”, poi avrai “Cache hit”.
   • Se hai configurato Redis, visita https://servbay-cakephp-test.local/cache-redis. Alla prima visita “Cache miss”, poi “Cache hit”.

Questo conferma che il tuo progetto CakePHP usa correttamente i servizi di cache di ServBay.

Note Importanti

• Credenziali database: Username/password predefiniti di ServBay (root/password) sono pensati solo per lo sviluppo locale. In produzione usa sempre credenziali sicure.
• Document root: Assicurati di impostare la document root del sito ServBay sulla cartella webroot del progetto CakePHP, non sulla root principale del progetto. È best practice.
• Compatibilità PHP: Verifica che la versione PHP selezionata in ServBay sia compatibile col CakePHP usato. Consulta la documentazione ufficiale CakePHP per i requisiti di versione.
• Porte ServBay: Se le porte predefinite (80 e 443) sono occupate da altri programmi, cambia la porta in ServBay e accedi usando la porta o aggiorna il file hosts.

Domande Frequenti (FAQ)

• D: Visitando servbay-cakephp-test.local vedo “Pagina non trovata”?
  • R: Controlla che la document root del sito corrisponda a /Applications/ServBay/www/servbay-cakephp-app/webroot.
  • Verifica che il server Web ServBay (Caddy/Nginx) sia attivo.
  • Verifica che il file hosts punti servbay-cakephp-test.local a 127.0.0.1 (generalmente ServBay lo fa automaticamente).
  • Verifica che il file .htaccess di CakePHP o le configurazioni del server siano corrette (quello in webroot/.htaccess di solito va bene di default).
• D: Connessione database fallita?
  • R: Controlla che il servizio DB ServBay (MySQL/PostgreSQL) sia attivo.
  • Controlla che i parametri in config/app_local.php (host, port, username, password, database) siano corretti e coincidano con quelli del servizio ServBay.
  • Verifica che il database servbay_cakephp_app sia stato creato.
• D: Il comando Composer (bin/cake) non è eseguibile?
  • R: Assicurati che la directory terminale sia quella della root progetto (/Applications/ServBay/www/servbay-cakephp-app).
  • Verifica che i pacchetti PHP e Composer siano attivi su ServBay.
  • Controlla che il comando php sia accessibile dal terminale (ServBay normalmente imposta il PATH, ma puoi usare il suo terminale integrato o configurarlo manualmente).

Conclusioni

Grazie a ServBay puoi configurare rapidamente un ambiente di sviluppo locale su macOS per progetti CakePHP. Le integrazioni predefinite di PHP, Composer, server Web e servizi database semplificano drasticamente tutto il processo. Questa guida ti ha mostrato come procedere dalla creazione del progetto, alla configurazione di base, fino all'integrazione di database relazionali e servizi cache, permettendoti di iniziare subito lo sviluppo con CakePHP. Sfrutta la semplicità di ServBay per concentrarti sul codice, lasciando da parte le complessità della configurazione ambiente.