Installazione e Avvio di Applicazioni Workerman in ServBay

Panoramica

Questo documento è una guida per gli utenti ServBay su come configurare e avviare rapidamente applicazioni di rete PHP ad alte prestazioni basate su Workerman nell’ambiente di sviluppo locale su macOS e Windows, sfruttando PHP e Composer integrati in ServBay. Workerman è una potente libreria PHP pensata per sviluppare servizi di rete che richiedono la gestione di molteplici connessioni simultanee, come server web, sistemi di messaggistica in tempo reale, server di gioco e altro ancora. ServBay offre una piattaforma pronta all’uso che semplifica drasticamente la configurazione ambientale necessaria per Workerman.

Cos'è Workerman?

Workerman è un framework open source PHP, scritto completamente in quest’ultimo, pensato per la comunicazione di rete asincrona ad alte prestazioni. Basato su EventLoop, realizza I/O asincrono e non bloccante, gestendo efficacemente grandi quantità di connessioni simultanee. Al contrario dei classici modelli PHP Web (tipo Apache/Nginx con PHP-FPM), le applicazioni Workerman restano residenti in memoria, ascoltando porte specifiche e gestendo direttamente le connessioni, evitando gli overhead legati alla distruzione dei processi a fine richiesta e migliorando notevolmente performance e throughput.

Con Workerman, gli sviluppatori possono facilmente creare:

• Server HTTP ad alte prestazioni, capaci persino di sostituire Apache/Nginx per richieste semplici statiche o dinamiche.
• Server WebSocket real-time per chat, notifiche, scambi di dati in tempo reale.
• Server TCP/UDP personalizzati per qualsiasi protocollo.
• Strumenti da linea di comando, task pianificati, microservizi, e molto altro.

Caratteristiche Principali e Vantaggi di Workerman

• Prestazioni elevate: Basato su architettura event-driven e I/O asincrono, gestisce migliaia di connessioni concorrenti offrendo prestazioni eccellenti.
• Supporto multi-protocollo: Supporta nativamente HTTP, WebSocket, TCP, UDP, consentendo anche protocolli personalizzati tramite interfacce flessibili.
• Facilità d’uso: API semplici e intuitive riducono la complessità della programmazione di rete asincrona; i programmatori PHP possono iniziare rapidamente.
• Estendibile e scalabile: Modello multi-processo che sfrutta CPU multi-core per scaling orizzontale e bilanciamento carico; facile integrazione con librerie PHP e pacchetti Composer.
• Integrato nell’ecosistema PHP: Gestione delle dipendenze tramite Composer per una fusione senza interruzioni nell’ambiente PHP.
• Modalità daemon: Può essere eseguito come processo in background, ideale per ambienti di produzione con stabilità garantita.

Workerman offre agli sviluppatori PHP gli strumenti per realizzare applicazioni di rete ad elevate prestazioni e comunicazione real-time.

Configurare l’Ambiente Workerman con ServBay

ServBay è un ambiente locale per lo sviluppo Web, che integra numerosi runtime (come PHP, Node.js, Python, Go, Java) e database/server come Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached ecc. La sua forza principale è essere “pronto all’uso” e fornire un ambiente Composer integrato: una vera comodità per installare e avviare progetti Workerman.

Questa guida utilizza dei semplici esempi per mostrare come configurare e lanciare Workerman su ServBay: un server HTTP, uno WebSocket e uno TCP.

TIP

Per ordine e praticità, ServBay consiglia di salvare tutti i progetti web locali nei seguenti percorsi:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

Tutti gli esempi di percorso in questa guida fanno riferimento a queste directory.

Prerequisiti

Prima di iniziare, verifica di avere:

1. ServBay installato e in esecuzione: Scarica la versione più recente dal sito ufficiale di ServBay.
2. PHP attivo in ServBay: Dal pannello di controllo ServBay, attiva la versione PHP desiderata. Workerman richiede almeno PHP 5.4, ma si consiglia PHP 7.x o 8.x per risultati ottimali.
3. Familiarità base con PHP e la shell: Devi conoscere la sintassi PHP e l’uso di strumenti da terminale.

Installazione Workerman

1. Verifica che Composer sia disponibile

Composer è già incluso in ServBay; non serve installarlo separatamente. Basta che ServBay sia avviato e PHP abilitato. ServBay configura automaticamente Composer per ogni versione PHP abilitata. Utilizza il terminale ServBay (o il terminale di sistema se PHP/Composer sono aggiunti nel PATH) per lavorare nell’ambiente ServBay.

Apri il terminale e digita il comando per verificare Composer:

composer -v

Se Composer è installato e configurato correttamente, vedrai la versione in output. In caso contrario, verifica che ServBay sia avviato e PHP abilitato.

2. Crea la directory del progetto

Spostati sulla cartella consigliata da ServBay e crea una nuova directory per il progetto, poi accedivi:

macOS:

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

Windows:

cd C:\ServBay\www
mkdir servbay-workerman-demo
cd servbay-workerman-demo

Abbiamo creato la directory servbay-workerman-demo per il progetto Workerman.

3. Installa Workerman con Composer

Dalla directory del progetto, esegui Composer per installare la libreria Workerman. Composer gestirà automaticamente tutte le dipendenze.

Percorso progetto:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

composer require workerman/workerman

Composer scaricherà Workerman e tutte le sue dipendenze nella cartella vendor del progetto.

Scrivere il Codice del Server HTTP Workerman

Il server HTTP è uno degli scenari d’uso più comuni di Workerman per web-app e API performanti.

Crea un file chiamato http_server.php (o altro nome a piacere, ad esempio server.php) nella cartella del progetto e inserisci il seguente codice PHP:

<?php
// Includi l'autoloader di Composer per usare le classi 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, specificando protocollo e indirizzo
// 'http://0.0.0.0:8080' crea un server HTTP su tutte le interfacce, porta 8080
// 0.0.0.0 consente accessi sia locali che dalla LAN; 8080 è il numero di porta.
$http_worker = new Worker('http://0.0.0.0:8080');

// Imposta il numero di processi Worker
// Qui impostato a 4 per utilizzare 4 processi PHP; regolalo secondo i core della CPU
$http_worker->count = 4;

// Definisce la logica di gestione delle richieste dal client (HTTP)
// $connection rappresenta la connessione, serve per inviare una risposta
// $request contiene le info della richiesta (URL, Headers, Body, ecc.)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Invia una semplice stringa come risposta HTTP al client
    // La gestione degli header HTTP è automatica
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// Avvia tutti i Worker
// Questo è il loop principale di Workerman: avvio del servizio e ascolto eventi
Worker::runAll();

Spiegazione del codice:

• require __DIR__ . '/vendor/autoload.php';: carica il file con classi autoload gestite da Composer, incluse Worker, Request, Response ecc.
• use Workerman\...;: importazione delle classi necessarie.
• new Worker('http://0.0.0.0:8080'): crea l’istanza Worker, specificando protocollo e indirizzo.
• $http_worker->count = 4;: numero di processi PHP da avviare. Più processi gestiscono meglio la concorrenza.
• $http_worker->onMessage = function(...) { ... }: callback per la gestione di ogni richiesta HTTP completa; $connection invia i dati, $request contiene la richiesta, Response genera la risposta standard.
• Worker::runAll();: avvia il loop Workerman, mettendo in ascolto tutte le istanze Worker.

Avviare il Server HTTP Workerman

Dalla cartella del progetto, usa il terminale per avviare il server HTTP:

Percorso progetto:

• macOS: /Applications/ServBay/www/servbay-workerman-demo
• Windows: C:\ServBay\www\servbay-workerman-demo

php http_server.php start

Modalità di esecuzione:

• Foreground: Il comando php http_server.php start lancia Workerman in primo piano; verranno mostrati log e info runtime. Stop con Ctrl+C. Utile per sviluppo/debug.
• Modalità daemon: In produzione, si usa l’argomento -d per eseguire come processo in background:

  php http_server.php start -d

  Il servizio sarà avviato in background e loggato su file.

Gestione processi:

Workerman supporta vari comandi per gestire i processi:

• Avvio: php http_server.php start (foreground) o php http_server.php start -d (background)
• Stop: php http_server.php stop (termina con eleganza dopo aver servito le richieste attive)
• Restart: php http_server.php restart (stop e nuovo start)
• Reload: php http_server.php reload (riavvia progressivamente i processi per permettere update del codice senza interrompere il servizio; attenzione alle funzioni come onWorkerStart)
• Stato: php http_server.php status (visualizza info su stato, memoria, connessioni ecc.)

Dopo l’avvio, visita http://localhost:8080 o http://127.0.0.1:8080 dal browser: vedrai Hello ServBay Workerman HTTP Server! sulla pagina.

Creare un Server WebSocket con Workerman

WebSocket consente una connessione persistente bidirezionale client-server: ideale per chat, giochi, trading in tempo reale. Workerman gestisce WebSocket in modo nativo.

1. Scrivi il codice del server WebSocket

   Crea nel progetto un file chiamato websocket_server.php e inserisci:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea una istanza Worker WebSocket, ascolta sulla porta 8081
   // 'websocket://0.0.0.0:8081' crea il server WebSocket e gestisce handshake
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Avvia 4 processi per gestire le connessioni
   $ws_worker->count = 4;
   
   // Logica per la nuova connessione
   // Triggerata alla connessione di un nuovo client
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nuova connessione WebSocket da " . $connection->getRemoteIp() . "\n";
   };
   
   // Logica di gestione messaggi
   // Esegue all’arrivo di un messaggio dal client WebSocket
   // $data contiene il messaggio già decodificato
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Messaggio ricevuto: " . $data . "\n";
       // Invio echo al client
       // Il metodo send() codifica automaticamente il frame WebSocket
       $connection->send('ServBay Workerman ha ricevuto: ' . $data);
   };
   
   // Logica di chiusura connessione
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Connessione WebSocket chiusa\n";
   };
   
   // Gestione errori (opzionale)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Errore: $code - $msg\n";
   };
   
   
   // Avvio dei Worker
   Worker::runAll();

2. Avvia il server WebSocket

   Dalla directory del progetto, avvia così:

   php websocket_server.php start

   Per il background, aggiungi l’opzione -d. Dopo l’avvio, puoi usare un client WebSocket (o tool del browser) per collegarti a ws://localhost:8081.

   Ad esempio, nel console JavaScript del browser:

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

   Dopo la connessione, vedrai nel terminale informazioni sulla connessione e messaggi ricevuti — anche il browser riceverà il messaggio echo dal server.

Creare un Server TCP con Workerman

Workerman consente anche la creazione di server TCP generici per ogni tipo di protocollo, utili per backend di giochi, IoT, comunicazioni personalizzate.

1. Scrivi il codice del server TCP

   Crea il file tcp_server.php e inserisci:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Crea un server TCP sulla porta 8082
   // 'tcp://0.0.0.0:8082' crea il server TCP; di default usa il protocollo Text (\n)
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Avvia 4 processi per gestire le connessioni
   $tcp_worker->count = 4;
   
   // Logica per la connessione
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nuova connessione TCP da " . $connection->getRemoteIp() . "\n";
       // Invia messaggio di benvenuto al client
       $connection->send("Benvenuto nel ServBay Workerman TCP Server!\n");
   };
   
   // Logica per la ricezione dei dati
   // $data è il dato TCP ricevuto dal client (già processato secondo protocollo)
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Dato ricevuto: " . $data;
       // Echo del dato inviato dal client
       $connection->send('ServBay Workerman ha ricevuto: ' . $data);
   };
   
   // Logica per la chiusura connessione
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Connessione TCP chiusa\n";
   };
   
   // Avvio dei Worker
   Worker::runAll();

2. Avvia il server TCP

   Dalla cartella progetto, esegui:

   php tcp_server.php start

   Puoi avviare anche in background (-d). Usa tool come telnet o netcat per collegarti a localhost:8082:

   # Con telnet
   telnet localhost 8082
   
   # Oppure con nc (netcat)
   nc localhost 8082

   Dopo la connessione, riceverai il messaggio di benvenuto. Scrivi qualcosa (invio per inviare): il server ti risponderà con un echo di ciò che hai scritto.

Note Importanti

• Conflitto porte: Assicurati che le porte usate da Workerman (8080, 8081, 8082 negli esempi) non siano impegnate da altri processi o servizi di ServBay/macOS. Se una porta è già occupata, Workerman mostrerà un errore e non avvierà il server. Verifica con lsof -i :numero_porta.
• Firewall: Il firewall locale potrebbe bloccare l’accesso da altri dispositivi. Per sviluppo locale non è normalmente un problema, ma se vuoi accedere da dispositivi in rete LAN assicurati che il firewall sia configurato correttamente.
• Relazione con i server Web ServBay: Workerman è un servizio indipendente e lavora su porte dedicate, separatamente da Caddy o Nginx. Elabora direttamente le connessioni (non tramite proxy, a meno che tu non configuri il reverse proxy). È ideale per applicazioni ad alta concorrenza e lunga durata (es. WebSocket); Caddy/Nginx restano consigliati per richieste HTTP brevi e tradizionali.
• Versione PHP: Verifica che la versione PHP usata sia compatibile. ServBay include e preconfigura diverse versioni; seleziona quella appropriata dal pannello di controllo.
• Estensioni: Workerman sfrutta alcune estensioni PHP per massimizzare performance e funzionalità: event in particolare (se presente, velocizza il framework), oltre a posix, pcntl (necessarie per la modalità multi-processo). ServBay abilita di default molte estensioni utili. Se riscontri problemi, verifica dal pannello ServBay che le estensioni siano attive.
• Log: In modalità daemon, l’output viene redirezionato su file di log. Monitora regolarmente i log per tenere traccia del funzionamento e diagnosticare errori.

FAQ - Domande Frequenti

• D: Come fermare il server Workerman?
  • R: Se sei in foreground (start), premi semplicemente Ctrl+C nel terminale. Se Workerman è avviato come daemon (start -d), usa il comando php tuoserver.php stop dalla cartella del progetto.
• D: Il server Workerman non si avvia, perché?
  • R: Spesso la causa è la porta impegnata. Controlla eventuali messaggi di errore sulla porta, cambia il numero della porta o termina il servizio che la utilizza. Usa lsof -i :numero_porta per vedere il processo che la occupa.
• D: Qual è la differenza tra Caddy/Nginx (ServBay) e Workerman? Quale scegliere?
  • R: Caddy/Nginx gestiscono HTTP/HTTPS tradizionale (spesso con PHP-FPM), dove i processi PHP possono terminare dopo aver gestito la singola richiesta. Workerman, al contrario, è un framework PHP asincrono che può fare da server HTTP e gestire anche WebSocket, TCP, UDP, restando residente in memoria: ottimo per richieste lunghe o molti client contemporanei come chat, giochi, robot IoT. Usa Caddy/Nginx per siti web convenzionali/API REST, Workerman per comunicazione in tempo reale. Puoi anche combinarli usando proxy inversi.
• D: Posso lanciare più app Workerman contemporaneamente in ServBay?
  • R: Sì. Ogni app Workerman va avviata in un processo PHP indipendente su una porta diversa. Scrivi uno script server distinto per ogni app e avviale da terminali separati (php tua_app.php start o in background). Le porte devono essere diverse.

Conclusioni

Grazie a questa guida, sai come configurare e avviare velocemente un progetto Workerman in ServBay, sfruttando l’efficienza dell’ambiente e la potenza del framework PHP asincrono. Unendo l’ambiente pronto all’uso di ServBay con Composer e PHP già configurati, puoi dedicarti completamente al business del tuo progetto Workerman senza preoccuparti delle dipendenze e delle configurazioni. Che tu debba creare servizi web ad alte prestazioni, app real-time con WebSocket o sistemi TCP personalizzati, ServBay è il compagno ideale per lo sviluppo locale con Workerman. Buon lavoro e buon divertimento con Workerman!