Configurazione e avvio di applicazioni Workerman in ServBay

Panoramica

Questo documento guida gli utenti di ServBay nel configurare rapidamente un ambiente di sviluppo locale su macOS per creare ed eseguire applicazioni di rete asincrone ad alte prestazioni basate su Workerman, sfruttando l’ambiente PHP integrato e Composer di ServBay. Workerman è una potente libreria PHP ideale per costruire servizi di rete ad alta concorrenza come server Web, sistemi di comunicazione real-time, server di gioco e altro ancora. ServBay offre un ambiente di sviluppo pronto all'uso, rendendo la configurazione di Workerman molto più semplice.

Che cos’è Workerman?

Workerman è un framework open source di comunicazione di rete asincrona scritto interamente in PHP. Basato su un sistema di event loop, implementa I/O asincroni non bloccanti, gestendo in modo efficiente un gran numero di connessioni concorrenti. Diversamente dai tradizionali modelli di sviluppo Web PHP (come Apache/Nginx + PHP-FPM), le applicazioni Workerman sono tipicamente processi residenti in memoria che ascoltano porte specifiche e gestiscono direttamente le connessioni. In questo modo si evitano gli overhead dovuti alla distruzione dei processi a ogni richiesta, migliorando notevolmente le prestazioni e il throughput.

Con Workerman, gli sviluppatori possono costruire facilmente:

• Server HTTP ad alte prestazioni, anche come alternativa ad Apache/Nginx per richieste statiche o dinamiche semplici.
• Server WebSocket real-time, come chat, notifiche push, aggiornamenti dati live ecc.
• Server TCP/UDP personalizzati per vari protocolli.
• Strumenti da linea di comando, job pianificati, microservizi, e altri servizi.

Caratteristiche principali e vantaggi di Workerman

• Alte prestazioni: Basato su event driven e I/O asincroni, può gestire una quantità massiccia di connessioni contemporanee, offrendo prestazioni eccellenti.
• Supporto multiprotocollo: Supporta nativamente HTTP, WebSocket, TCP, UDP e altri protocolli di rete popolari, permettendo anche l’implementazione di protocolli personalizzati.
• Facilità d'uso: API semplici e intuitive che riducono la complessità della programmazione di rete asincrona per gli sviluppatori PHP.
• Scalabilità flessibile: Supporta un modello multiprocesso, sfruttando la CPU multicore per lo scaling orizzontale e il bilanciamento del carico. L’integrazione con Composer e altre librerie PHP è semplice.
• Integrazione con l’ecosistema PHP: Essendo una libreria PHP, si integra perfettamente con Composer e tutto l’ecosistema PHP.
• Modalità daemon: Supporta l’esecuzione in background come servizio daemon, ideale per la produzione e per garantire la continuità del servizio.

Workerman apre agli sviluppatori PHP le porte alla creazione di applicazioni di rete ad alte prestazioni, real-time e con alta concorrenza.

Configurare l’ambiente di sviluppo Workerman con ServBay

ServBay è uno strumento creato appositamente per sviluppatori Web che integra runtime per linguaggi come PHP, Node.js, Python, Go, Java, oltre a server e database popolari come Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached e altri. Il più grande vantaggio di ServBay è il suo approccio “pronto all'uso”, con Composer già integrato e configurato: un’enorme comodità per installare ed eseguire progetti Workerman.

Questa guida presenta una serie di semplici esempi che mostrano come configurare rapidamente e avviare Workerman in ServBay: realizzeremo un server HTTP, un server WebSocket e un server TCP.

TIP

Per una gestione ordinata, ServBay consiglia di memorizzare tutti i progetti web locali nella cartella /Applications/ServBay/www. Tutti gli esempi in questa guida fanno riferimento a questa posizione.

Prerequisiti

Prima di iniziare, assicurati di:

1. Aver installato e avviato ServBay: Scarica la versione più recente dal sito ufficiale di ServBay.
2. Aver abilitato PHP in ServBay: Nel pannello di controllo di ServBay, verifica che la versione PHP che vuoi utilizzare sia attiva. Workerman richiede almeno PHP 5.4; si consiglia PHP 7.x o 8.x per migliori prestazioni.
3. Conoscere le basi di programmazione PHP e comandi da terminale: Dovrai essere familiare con la sintassi PHP e con l’utilizzo della shell.

Installare Workerman

1. Verifica disponibilità di Composer

ServBay include Composer, quindi non occorre installarlo separatamente. Assicurati che ServBay sia avviato e che la versione PHP desiderata sia abilitata. ServBay configura automaticamente Composer per ciascuna versione PHP attiva. Puoi lavorare dal terminale interno di ServBay oppure dal terminale di sistema (se PHP e Composer sono aggiunti al PATH di sistema).

Apri il terminale e verifica l’installazione di Composer con:

composer -v

Se Composer è installato e configurato correttamente nell’ambiente PHP di ServBay, visualizzerai le informazioni sulla versione. Se il comando non viene riconosciuto, assicurati che ServBay sia in esecuzione e che PHP sia abilitato.

2. Crea la directory di progetto

Spostati nella cartella radice consigliata da ServBay e crea una nuova directory per il progetto, quindi accedici:

cd /Applications/ServBay/www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

Abbiamo creato una cartella chiamata servbay-workerman-demo dove archivieremo i file di Workerman.

3. Installa Workerman con Composer

All’interno della directory (/Applications/ServBay/www/servbay-workerman-demo), installa Workerman tramite Composer:

composer require workerman/workerman

Composer scaricherà automaticamente Workerman e le sue dipendenze all’interno della cartella vendor.

Scrivere il codice di un server HTTP con Workerman

Il server HTTP è uno degli scenari d’uso più comuni di Workerman, ideale sia per web app di alta prestazione che per API.

Nella directory del progetto, crea un file chiamato http_server.php (o con altro nome a tua scelta, ad esempio server.php) e inserisci il seguente codice PHP:

<?php
// Includi l'autoloader di Composer per usare le classi di Workerman
require __DIR__ . '/vendor/autoload.php';

// Importa la classe Worker di Workerman
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// Crea un’istanza Worker che ascolta protocollo e indirizzo specificati
// 'http://0.0.0.0:8080' significa che il server HTTP ascolta sulla porta 8080 di tutte le interfacce di rete
// 0.0.0.0 consente accessi sia da locale che dalla rete locale; 8080 è la porta gestita.
$http_worker = new Worker('http://0.0.0.0:8080');

// Imposta il numero di processi Worker
// Qui impostato a 4: avvia quattro processi PHP indipendenti per gestire le richieste; puoi modificarlo in base ai core della CPU
$http_worker->count = 4;

// Definisci la logica per gestire le richieste HTTP in arrivo dai client
// $connection rappresenta la connessione, attraverso cui si manda la risposta
// $request contiene le informazioni della richiesta (URL, Headers, Body, ecc.)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Invia una semplice stringa come risposta HTTP al client
    // Workerman gestirà automaticamente intestazioni e dettagli HTTP
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// Avvia tutti gli istanze Worker
// Questo è il ciclo principale: inizia l’ascolto delle porte e la gestione degli eventi
Worker::runAll();

Spiegazione del codice:

• require __DIR__ . '/vendor/autoload.php';: Carica l’autoloader di Composer per abilitare l’utilizzo delle classi Workerman (Worker, Request, Response ecc).
• use Workerman\...;: Importa le classi necessarie.
• new Worker('http://0.0.0.0:8080'): Crea un’istanza Workerman e specifica il protocollo e la porta di ascolto.
• $http_worker->count = 4;: Numero di processi Worker lanciati. Aumentare il valore sfrutta la CPU multicore per maggiore concorrenza.
• $http_worker->onMessage = function(TcpConnection $connection, Request $request) { ... };: Definisce la callback che gestisce ciascuna richiesta HTTP ricevuta. $connection per rispondere al client, $request per i dettagli della richiesta. Con Response si prepara la risposta HTTP standard.
• Worker::runAll();: Avvia il loop Workerman per tutte le istanze Worker definite.

Avvio del server HTTP Workerman

All’interno della cartella di progetto (/Applications/ServBay/www/servbay-workerman-demo), esegui nel terminale:

php http_server.php start

Modalità operative:

• Modalità in primo piano (Foreground): Con il comando php http_server.php start, Workerman gira in primo piano, mostrando informazioni e log in tempo reale. Puoi fermarlo con Ctrl+C: modalità consigliata per sviluppo e debug.
• Modalità daemon (background): Per la produzione, si utilizza -d:

  php http_server.php start -d

  Workerman girerà in background; output e log andranno su file (di default nella directory Workerman o in percorso specificato).

Gestione dei processi:

Workerman offre comandi di gestione semplici:

• Avvio: php http_server.php start (foreground) oppure php http_server.php start -d (daemon)
• Stop: php http_server.php stop (interrompe dopo aver completato le richieste in corso)
• Restart: php http_server.php restart (ferma e riavvia)
• Reload: php http_server.php reload (riavvia gradualmente i processi figlio senza interruzione del servizio, ideale per aggiornare il codice)
• Stato: php http_server.php status (mostra lo stato di Workerman, uso di memoria, numero di connessioni ecc.)

Ora puoi aprire il browser e accedere a http://localhost:8080 oppure http://127.0.0.1:8080. Visualizzerai il messaggio Hello ServBay Workerman HTTP Server!.

Creare un server WebSocket con Workerman

Il protocollo WebSocket permette una comunicazione bidirezionale persistente tra client e server: soluzione ideale per app real-time come chat, notifiche push, giochi online, e altro. Workerman include supporto avanzato per WebSocket.

1. Codice del server WebSocket

   Crea nella directory del progetto un file chiamato websocket_server.php con il seguente contenuto:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea l’istanza del server WebSocket sulla porta 8081
   // 'websocket://0.0.0.0:8081' attiva il protocollo WebSocket
   // Workerman gestisce automaticamente l’handshake
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Avvia 4 processi per la gestione delle connessioni
   $ws_worker->count = 4;
   
   // Logica all’apertura di una connessione
   // Triggerata quando un nuovo client si collega al server
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nuova connessione WebSocket da " . $connection->getRemoteIp() . "\n";
   };
   
   // Logica alla ricezione di un messaggio
   // Triggerata all’arrivo di dati dal client tramite WebSocket
   // $data contiene il messaggio decodificato dal client
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Messaggio ricevuto: " . $data . "\n";
       // Invia una risposta di conferma al client (eco)
       // $connection->send() codifica i dati come frame WebSocket
       $connection->send('ServBay Workerman ha ricevuto: ' . $data);
   };
   
   // Logica alla chiusura della connessione
   // Triggerata quando il client si disconnette
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Connessione WebSocket chiusa\n";
   };
   
   // Gestione degli errori (opzionale)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Errore: $code - $msg\n";
   };
   
   
   // Avvia tutte le istanze Worker
   Worker::runAll();

2. Avvio del server WebSocket

   Nel progetto, lancia il server con:

   php websocket_server.php start

   Puoi usare anche l’opzione -d per farlo girare in background. Una volta in funzione, puoi collegarti a ws://localhost:8081 tramite un client WebSocket.

   Per esempio, dalla Console del browser con JavaScript:

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("Connessione WebSocket aperta");
     ws.send("Ciao dal browser!"); // Invia messaggio
   };
   
   ws.onmessage = function(event) {
     console.log("Messaggio dal server:", event.data); // Ricevi messaggio
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Connessione WebSocket chiusa correttamente, codice=" + event.code + " motivo=" + event.reason);
     } else {
       console.error("Connessione WebSocket terminata inaspettatamente");
     }
   };
   
   ws.onerror = function(error) {
     console.error("Errore WebSocket:", error);
   };
   
   // Per chiudere manualmente
   // ws.close();

   Potrai vedere in terminale la logica di connessione, ricezione ed eco dei messaggi, mentre nel browser arriverà il riscontro del server.

Creare un server TCP con Workerman

Workerman può essere usato anche per realizzare server TCP generici, ideali per backend di giochi, piattaforme IoT, servizi di comunicazione personalizzati e altro.

1. Codice del server TCP

   Crea un file tcp_server.php nella directory progetto con questo contenuto:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea un’istanza di server TCP sulla porta 8082
   // 'tcp://0.0.0.0:8082' crea un server TCP
   // Di default, Workerman usa il protocollo Text con '\n' come terminatore
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Avvia 4 processi per le connessioni
   $tcp_worker->count = 4;
   
   // Logica all’instaurarsi della connessione
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nuova connessione TCP da " . $connection->getRemoteIp() . "\n";
       // All’avvio della connessione invia un messaggio di benvenuto
       $connection->send("Benvenuto su ServBay Workerman TCP Server!\n");
   };
   
   // Logica alla ricezione dei dati
   // $data è ciò che viene ricevuto dal client dopo essere stato processato dal protocollo
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Dato ricevuto: " . $data;
       // Invia eco dei dati ricevuti
       $connection->send('ServBay Workerman ha ricevuto: ' . $data);
   };
   
   // Alla chiusura della connessione
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Connessione TCP chiusa\n";
   };
   
   // Avvia tutte le istanze Worker
   Worker::runAll();

2. Avvio del server TCP

   Avvia nel terminale:

   php tcp_server.php start

   Puoi utilizzare anche -d per background. Dopo l’avvio, collega un client TCP a localhost:8082.

   Su macOS/Linux, usa un secondo terminale con:

   # Usando telnet
   telnet localhost 8082
   
   # Oppure netcat (nc)
   nc localhost 8082

   Una volta connesso, visualizzerai il messaggio di benvenuto del server. Scrivendo testo (terminato da invio, visto che si usa il protocollo Text), il server farà l’eco del contenuto inviato.

Note importanti

• Porte occupate: Assicurati che le porte usate da Workerman (8080, 8081, 8082 negli esempi) non siano impegnate da altri servizi su macOS o da altri processi in ServBay. In caso di conflitto la partenza fallirà: usa lsof -i :numero_porta per verificare.
• Firewall: Il firewall di macOS potrebbe bloccare connessioni in ingresso alle porte. In ambiente locale di solito non è un problema, ma se hai necessità di accesso da altri dispositivi in LAN verifica le impostazioni del firewall.
• Relazione con Web server di ServBay: Workerman ascolta su proprie porte e gira in modo indipendente rispetto a Caddy/Nginx. Di solito le applicazioni Workerman gestiscono le connessioni direttamente e non tramite proxy (tranne se configuri reverse proxy appositi). Workerman è ideale per real-time e connessioni persistenti (WebSocket), mentre Caddy/Nginx restano la scelta ottimale per HTTP classico.
• Versione PHP: Verifica che la versione di PHP usata soddisfi i requisiti minimi. ServBay include più versioni tra cui scegliere.
• Estensioni PHP: Workerman sfrutta alcune estensioni PHP per ottenere migliori performance: ad es. event (se installata e abilitata, sarà preferita), posix, pcntl per il multiprocesso. ServBay le attiva di default, ma in caso di problemi controlla nel pannello di controllo che siano abilitate per la versione PHP in uso.
• Log: In modalità daemon, Workerman invia log e output su file. Monitora periodicamente i log per verificare lo stato dell’applicazione o possibili errori.

Domande frequenti (FAQ)

• D: Come posso fermare un server Workerman?
  • R: Se gira in foreground (start), basta premere Ctrl+C nel terminale. Se gira in background (start -d), usa il comando php nome_file_server.php stop dalla directory di progetto.
• D: Perché Workerman non si avvia?
  • R: La causa più comune è la porta occupata. Controlla il messaggio di errore in terminale. Puoi cambiare porta oppure interrompere il programma che la sta usando (lsof -i :porta per individuarlo).
• D: Differenze tra Caddy/Nginx di ServBay e Workerman? Quando scegliere uno o l’altro?
  • R: Caddy/Nginx sono server HTTP/HTTPS tradizionali, lavorano spesso con PHP-FPM, e ogni richiesta può terminare il processo PHP dopo l'elaborazione. Workerman è un framework asincrono PHP, può anche servire HTTP, ma in più supporta WebSocket, TCP ecc., mantenendo i processi in memoria ideali per alta concorrenza e real-time. Usa Caddy/Nginx per siti web e API classiche; Workerman per chat, giochi, IoT, connessioni persistenti. Puoi combinarli, ad esempio usando reverse proxy di Caddy/Nginx verso porte Workerman.
• D: Posso eseguire più applicazioni Workerman in ServBay contemporaneamente?
  • R: Certamente. Ogni app Workerman deve essere avviata in un processo PHP separato e deve ascoltare una porta diversa. Crea uno script di avvio per ogni app e lancia i comandi php tuo_file_server.php start (frontend/background) in terminale/distinti processi. Attento solo a non usare porte duplicate.

Conclusione

In questa guida hai scoperto come configurare e avviare rapidamente un progetto Workerman grazie a ServBay, un potente ambiente di sviluppo locale. La natura asincrona e le alte prestazioni di Workerman offrono agli sviluppatori PHP gli strumenti giusti per creare la nuova generazione di applicazioni di rete. Approfittando dell’integrazione pronta all’uso di Composer e delle versioni PHP in ServBay, puoi concentrarti sul codice e sulla logica della tua app Workerman, senza complicazioni di setup complessi. Che tu debba costruire servizi web efficienti, app real-time o backend per WebSocket, ServBay è il partner locale ideale per lo sviluppo con Workerman. Buona esplorazione nel mondo Workerman!