Creazione e avvio di un progetto Webman con ServBay

Cos’è Webman?

Webman è un framework Web PHP asincrono ad alte prestazioni basato su Workerman, progettato per la creazione di applicazioni Web ad alta concorrenza e performance. Diversamente dai framework tradizionali sincroni e bloccanti, Webman utilizza un modello I/O asincrono, guidato da eventi, eccellendo nella gestione di traffico massivo e richieste simultanee. Webman offre API chiare e semplici, un sistema di estensioni flessibile, risultando ideale per applicazioni in tempo reale, servizi API, microservizi e altro ancora.

Principali caratteristiche e vantaggi di Webman

• Alte prestazioni: Grazie a Workerman e al modello I/O asincrono/event-driven, gestisce un grandissimo numero di connessioni con throughput superiore ai framework sincroni tradizionali.
• Facilità d’uso: API intuitive e funzioni ricche consentono agli sviluppatori di iniziare subito a creare applicazioni.
• Supporto multi-protocollo: Integrato per HTTP, WebSocket e altri protocolli applicativi diffusi, ideale per servizi di tipologia diversa.
• Estensione flessibile: Facilmente espandibile tramite pacchetti Composer, plugin e middleware.
• Consumo di risorse basso: A differenza del modello classico web server + PHP-FPM, Webman gira come processo residente in memoria, riducendo l’impatto sulle risorse.
• Community forte: Un’ampia base di sviluppatori attivi e ricca documentazione.

Webman consente una rapida creazione di applicazioni Web e servizi API ad alte prestazioni e affidabilità, particolarmente adatto per gestire scenari ad alta concorrenza e bassa latenza.

Creazione e avvio di un progetto Webman con ServBay

Questa guida illustra nel dettaglio come creare e avviare un semplice progetto Web con Webman nell’ambiente locale ServBay. Verranno mostrati i passaggi per installare Webman, scrivere la logica base per routing e controller, e integrare i servizi di database (MySQL, PostgreSQL) e cache (Redis, Memcached) forniti da ServBay.

TIP

ServBay consiglia di archiviare tutti i progetti e siti web locali nella directory /Applications/ServBay/www per una gestione centralizzata, ad esempio per la configurazione dei siti locali (precedentemente chiamati “host”).

Prerequisiti

Prima di iniziare, assicurati di aver completato i seguenti passaggi:

1. Installazione di ServBay: ServBay è stato installato correttamente su macOS. Offre un ambiente di sviluppo “tutto in uno” con PHP, Composer, MySQL, PostgreSQL, Redis, Memcached e tutti gli strumenti necessari per questa guida.
2. Abilitazione dei pacchetti necessari: Tramite il pannello di controllo ServBay verifica che i seguenti pacchetti siano installati e in esecuzione:
   • La versione PHP desiderata (consigliata la versione più recente, es. PHP 8.x)
   • Composer (incluso di default)
   • MySQL
   • PostgreSQL
   • Redis
   • Memcached
   • Assicurati che la versione PHP scelta abbia abilitati le estensioni memcached, redis, pdo_mysql, pdo_pgsql ecc. Di norma ServBay le attiva automaticamente, puoi verificarlo nella sezione di configurazione PHP.
3. Accesso al terminale: Essere pratici con il terminale di macOS.

Installazione di Webman

1. Verifica disponibilità Composer

   ServBay include Composer preinstallato e preconfigurato per l’uso diretto dal terminale. Controlla con il comando:

   composer --version

   Se viene visualizzata la versione di Composer, tutto è pronto.

2. Accedi alla directory dei siti ServBay

   Apri il terminale e spostati nella directory radice consigliata da ServBay:

   cd /Applications/ServBay/www

3. Crea il progetto Webman con Composer

   Utilizza il comando create-project di Composer per installare Webman in una directory specifica. Il progetto sarà chiamato servbay-webman-app:

   composer create-project workerman/webman servbay-webman-app

   Composer scaricherà Webman e le dipendenze nella cartella servbay-webman-app.

4. Accedi alla cartella del progetto

   Una volta completata l’installazione, entra nella directory creata:

   cd servbay-webman-app

5. Installa i componenti necessari

   Per testare integrazioni con database e cache, installa i seguenti pacchetti Composer extra. Webman solitamente utilizza illuminate/database (il componente DB di Laravel), illuminate/redis ecc. L’opzione -W (--with-dependencies) aiuta a risolvere problemi di compatibilità tra dipendenze.

   composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper

   Questo comando installerà ORM per database, client Redis, paginazione, gestore eventi e strumenti di debug.

Creazione del database e della tabella

Per consentire al codice di esempio di funzionare, crea il database e la tabella users sia su MySQL che su PostgreSQL di ServBay. La password utente predefinita per il database root è password.

Puoi usare gli strumenti grafici ServBay (phpMyAdmin o pgAdmin, accessibili dal pannello) oppure il terminale per eseguire i seguenti comandi SQL.

1. Crea il database webman_app

   • MySQL:

     CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   • PostgreSQL:

     CREATE DATABASE webman_app;

2. Crea la tabella users nel database webman_app

   • MySQL:

     USE webman_app;
     CREATE TABLE users (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

   • PostgreSQL:

     \c webman_app; -- Connessione al nuovo database
     CREATE TABLE users (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

Sviluppo del codice del progetto web

Aggiungi ora il codice per definire le route, creare i controller e implementare la logica di interazione con database e sistemi di cache.

1. Configurazione delle route

   Modifica il file config/route.php nella directory root del progetto ed aggiungi:

   <?php
   
   use Webman\Route;
   use app\controller\IndexController;
   use app\controller\CacheController;
   use app\controller\DatabaseController;
   
   // Definizione della route root, mappata al metodo index di IndexController
   Route::any('/', [IndexController::class, 'index']);
   
   // Route per la cache
   Route::any('/memcached', [CacheController::class, 'memcached']);
   Route::any('/redis', [CacheController::class, 'redis']);
   
   // Route per il database
   Route::any('/mysql-add', [DatabaseController::class, 'mysqlAdd']);
   Route::any('/mysql', [DatabaseController::class, 'mysqlGet']);
   Route::any('/pgsql-add', [DatabaseController::class, 'pgsqlAdd']);
   Route::any('/pgsql', [DatabaseController::class, 'pgsqlGet']);
   
   // Puoi aggiungere altre route qui...

2. Creazione dei file controller

   Nella cartella app/controller crea i file IndexController.php, CacheController.php e DatabaseController.php, e aggiungi il seguente codice.

   • app/controller/IndexController.php: gestisce le richieste alla root.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response; // Importa la classe Response
     
     class IndexController
     {
         /**
          * Metodo di esempio per la root
          * @param Request $request Oggetto request corrente
          * @return Response Una istanza di Response
          */
         public function index(Request $request): Response // Tipo di ritorno esplicito
         {
             // Restituisce una semplice risposta testuale
             return response('Hello ServBay & Webman!'); // Messaggio di benvenuto aggiornato
         }
     }

   • app/controller/CacheController.php: per l’utilizzo di Memcached e Redis.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use Memcached; // Importa la classe Memcached
     use support\Redis; // Facade Redis fornito da Webman
     
     class CacheController
     {
         /**
          * Dimostrazione utilizzo Memcached
          * @param Request $request
          * @return Response
          */
         public function memcached(Request $request): Response
         {
             // Connessione al server Memcached, ServBay di default su 127.0.0.1:11211
             $memcached = new Memcached();
             $memcached->addServer('127.0.0.1', 11211);
     
             // Imposta una chiave cache, con durata 60 secondi
             $success = $memcached->set('servbay_key', 'Hello Memcached from ServBay!', 60); // Chiave e valore aggiornati
             if (!$success) {
                  return response('Impossibile impostare la chiave Memcached', 500);
             }
     
             // Recupera il valore dalla cache
             $value = $memcached->get('servbay_key'); // Recupero chiave
     
             // Risposta con il valore trovato
             return response($value ?: 'Chiave Memcached non trovata o scaduta'); // Messaggio in caso di assenza
         }
     
         /**
          * Dimostrazione utilizzo Redis
          * @param Request $request
          * @return Response
          */
         public function redis(Request $request): Response
         {
             // Imposta una chiave cache tramite Redis Facade
             Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // Chiave e valore aggiornati
     
             // Recupera il valore dalla cache tramite Redis Facade
             $value = Redis::get('servbay_redis_key'); // Recupero chiave
     
             // Risposta con il valore trovato
             return response($value ?: 'Chiave Redis non trovata'); // Messaggio in caso di assenza
         }
     }

   • app/controller/DatabaseController.php: per operazioni su MySQL e PostgreSQL.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use support\Db; // Facade Db fornito da Webman
     
     class DatabaseController
     {
         /**
          * Aggiungi utente su MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlAdd(Request $request): Response
         {
             try {
                 // Connessione DB ('mysql') e inserimento
                 Db::connection('mysql')->table('users')->insert([
                     'name' => 'ServBay Webman MySQL User', // Dato di esempio
                     'email' => 'mysql_demo@servbay.test', // Mail di esempio
                     'created_at' => date('Y-m-d H:i:s') // Data inserimento
                 ]);
                 return response('Utente aggiunto su MySQL'); // Risposta aggiornata
             } catch (\Exception $e) {
                 return response('Errore nell’aggiunta utente su MySQL: ' . $e->getMessage(), 500); // Gestione errori
             }
         }
     
         /**
          * Recupera la lista utenti da MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlGet(Request $request): Response
         {
             try {
                 // Recupere tutti gli utenti DB ('mysql')
                 $users = Db::connection('mysql')->table('users')->get();
                 // Risposta JSON con lista utenti
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Content-Type esplicitato
             } catch (\Exception $e) {
                  return response('Errore nel recupero utenti da MySQL: ' . $e->getMessage(), 500); // Gestione errori
             }
         }
     
         /**
          * Aggiungi utente su PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlAdd(Request $request): Response
         {
              try {
                 // Connessione DB ('pgsql') e inserimento
                 Db::connection('pgsql')->table('users')->insert([
                     'name' => 'ServBay Webman PgSQL User', // Dato di esempio
                     'email' => 'pgsql_demo@servbay.test', // Mail di esempio
                     'created_at' => date('Y-m-d H:i:s') // Data inserimento
                 ]);
                 return response('Utente aggiunto su PostgreSQL'); // Risposta aggiornata
              } catch (\Exception $e) {
                 return response('Errore nell’aggiunta utente su PostgreSQL: ' . $e->getMessage(), 500); // Gestione errori
              }
         }
     
         /**
          * Recupera la lista utenti da PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlGet(Request $request): Response
         {
              try {
                 // Recupera tutti gli utenti DB ('pgsql')
                 $users = Db::connection('pgsql')->table('users')->get();
                 // Risposta JSON con lista utenti
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // Content-Type esplicitato
              } catch (\Exception $e) {
                 return response('Errore nel recupero utenti da PostgreSQL: ' . $e->getMessage(), 500); // Gestione errori
              }
         }
     }

3. Configurazione della connessione database

   Modifica il file config/database.php nella directory root e aggiorna i parametri di connessione per MySQL e PostgreSQL. L’host di default è 127.0.0.1, porta 3306 (MySQL) e 5432 (PostgreSQL), utente root password password.

   <?php
   /**
    * Configurazione database
    */
   return [
       // Connessione di default
       'default' => 'mysql',
   
       // Dettagli connessioni
       'connections' => [
           'mysql' => [
               'driver'    => 'mysql',
               // Host e porta MySQL predefiniti ServBay
               'host'      => '127.0.0.1',
               'port'      => 3306,
               // Nome database creato precedentemente
               'database'  => 'webman_app',
               // Utente MySQL ServBay
               'username'  => 'root',
               // Password MySQL ServBay
               'password'  => 'password',
               'charset'   => 'utf8mb4',
               'collation' => 'utf8mb4_unicode_ci',
               'prefix'    => '',
               'strict'    => true,
               'engine'    => null,
           ],
           'pgsql' => [
               'driver'   => 'pgsql',
               // Host e porta PostgreSQL predefiniti ServBay
               'host'     => '127.0.0.1',
               'port'     => 5432,
                // Nome database creato precedentemente
               'database' => 'webman_app',
                // Utente PostgreSQL ServBay
               'username' => 'root',
                // Password PostgreSQL ServBay
               'password' => 'password',
               'charset'  => 'utf8',
               'prefix'   => '',
               'schema'   => 'public',
               'sslmode'  => 'prefer', // oppure require, verify-ca, verify-full
           ],
           // Puoi aggiungere altre connessioni database qui...
       ],
   ];

   Importante: In produzione, modifica la password di default ed evita di inserire credenziali sensibili direttamente nei file codice.

Avvio del progetto Webman

Il progetto Webman si avvia tramite il suo script start.php, che lancia il processo Workerman. Diversamente dai web server classici (Nginx/Apache + PHP-FPM), Webman è un’applicazione residente in memoria e asincrona.

Dalla directory progetto (/Applications/ServBay/www/servbay-webman-app) esegui:

php start.php start

Vedrai i messaggi di avvio di Webman; per default il server ascolta richieste HTTP su 127.0.0.1:8787.

• Nota: Il comando php utilizza la versione ServBay dedicata; ServBay aggiorna l’ambiente del terminale per usare il PHP installato localmente.
• Per avviare Webman in background usa il parametro -d: php start.php start -d.
• Per fermare Webman: php start.php stop.
• Per riavviarlo: php start.php restart.
• Per riavvio soft (senza interrompere le richieste): php start.php reload.

Test del progetto

Dopo l’avvio, Webman ascolterà su 127.0.0.1:8787 e potrai testare le varie funzionalità con i seguenti URL nel browser:

• http://localhost:8787/: vedrai la pagina con il messaggio Hello ServBay & Webman!.
• http://localhost:8787/memcached: visualizzerai Hello Memcached from ServBay!, confermando la connessione e uso del servizio Memcached ServBay.
• http://localhost:8787/redis: visualizzerai Hello Redis from ServBay!, confermando la connessione e uso del servizio Redis ServBay.
• http://localhost:8787/mysql-add: visualizzerai Utente aggiunto su MySQL, che inserirà un nuovo record nella tabella users sul database MySQL.
• http://localhost:8787/mysql: visualizzerai l’output in formato JSON con l’elenco utenti della tabella users di MySQL.
• http://localhost:8787/pgsql-add: visualizzerai Utente aggiunto su PostgreSQL, che inserirà un nuovo record nella tabella users sul database PostgreSQL.
• http://localhost:8787/pgsql: visualizzerai l’output in formato JSON con l’elenco utenti della tabella users di PostgreSQL.

Se riscontri problemi con questi URL, controlla i messaggi di errore nel terminale Webman e verifica che i servizi MySQL, PostgreSQL, Redis, Memcached siano attivi in ServBay e che le estensioni PHP siano abilitate.

FAQ – Domande frequenti

• D: Il comando php start.php start non viene trovato?
  • R: Assicurati di essere nella directory servbay-webman-app e che il PHP installato da ServBay sia configurato correttamente nel PATH del sistema (ServBay lo gestisce in automatico).
• D: Impossibile accedere a localhost:8787?
  • R: Controlla eventuali errori in terminale. Assicurati che la porta 8787 sia libera (altrimenti modifica il file di configurazione, ad esempio config/server.php).
• D: Errore di connessione al database?
  • R: Verifica che i servizi MySQL e PostgreSQL siano attivi in ServBay. Controlla che i parametri in config/database.php (host, porta, nome, utente, password) corrispondano alla configurazione ServBay (default utente root, password password). Assicurati che il database webman_app e la tabella users siano stati creati.
• D: Problemi di connessione a Memcached o Redis?
  • R: Verifica che i servizi Memcached e Redis siano attivi in ServBay. Controlla che gli indirizzi e porte in app/controller/CacheController.php siano corretti (127.0.0.1:11211 e 127.0.0.1:6379). Verifica che la versione PHP abbia le estensioni memcached e redis abilitate.

Conclusione

Seguendo questi passaggi hai creato, configurato e avviato con successo un progetto base Webman nell’ambiente di sviluppo locale ServBay. Hai imparato a sfruttare i servizi integrati di ServBay per allestire rapidamente Webman, con supporto a database e sistemi di cache. Le elevate prestazioni di Webman, unite alla praticità di ServBay, offrono una solida base per lo sviluppo di applicazioni PHP asincrone. Speriamo che questa guida ti aiuti a costruire ottime web-app e API con ServBay e Webman.