Jak uruchomić i skonfigurować aplikację Workerman w ServBay

Wprowadzenie

Ten dokument wyjaśnia, jak użytkownicy ServBay mogą sprawnie konfigurować i uruchamiać aplikacje sieciowe o wysokiej wydajności, bazujące na Workerman, przy użyciu zintegrowanego środowiska PHP i menedżera zależności Composer w ServBay. Workerman to potężna biblioteka PHP przeznaczona do tworzenia różnorodnych usług wymagających obsługi wielu równoczesnych połączeń, np. serwerów WWW, serwerów komunikacji w czasie rzeczywistym czy backendów gier. ServBay zapewnia gotową platformę deweloperską, znacząco upraszczając proces konfiguracji środowiska dla Workerman.

Czym jest Workerman?

Workerman to w pełni otwartoźródłowy, wysoko wydajny asynchroniczny framework komunikacyjny napisany w PHP. Dzięki mechanizmowi pętli zdarzeń EventLoop, realizuje asynchroniczne, nieblokujące operacje I/O, umożliwiając obsługę ogromnej liczby połączeń jednocześnie. W przeciwieństwie do tradycyjnego modelu webowego PHP (np. Apache/Nginx + PHP-FPM), aplikacje Workerman uruchamiane są jako procesy rezydujące w pamięci, bezpośrednio nasłuchujące na wybranych portach. Pozwala to uniknąć kosztów zamykania procesu po każdym żądaniu i znacząco zwiększa wydajność oraz przepustowość aplikacji.

Workerman umożliwia łatwe tworzenie:

• wysoko wydajnych serwerów HTTP, które mogą zastąpić Apache/Nginx w obsłudze prostych zapytań,
• serwerów WebSocket do aplikacji takich jak czaty, systemy powiadomień w czasie rzeczywistym,
• serwerów TCP/UDP opartych o niestandardowe protokoły,
• narzędzi CLI, zadań planowanych, mikroserwisów.

Główne cechy i zalety Workerman

• Wysoka wydajność: Oparty o zdarzenia i nieblokujące I/O, obsługuje ogromną liczbę równoczesnych połączeń, oferując świetne rezultaty.
• Wieloprotokołowość: Obsługuje HTTP, WebSocket, TCP, UDP, a także umożliwia definiowanie własnych protokołów.
• Prosta obsługa: Przyjazne API ułatwia rozpoczęcie pracy, nawet początkującym developerom PHP.
• Elastyczność: Model wieloprocesowy pozwala na wykorzystanie wielu rdzeni CPU oraz łatwą integrację z pakietami Composer i innymi bibliotekami PHP.
• Integracja z ekosystemem PHP: Jako biblioteka PHP korzysta z całego ekosystemu, z zarządzaniem zależnościami przez Composer.
• Tryb demonowy: Obsługa pracy w tle jako daemon sprawia, że Workerman nadaje się do stabilnych wdrożeń produkcyjnych.

Workerman otwiera przed twórcami PHP drzwi do świata aplikacji sieciowych o wysokiej wydajności, w czasie rzeczywistym i z obsługą wielu połączeń.

Tworzenie środowiska do pracy z Workerman w ServBay

ServBay to wszechstronne, lokalne środowisko deweloperskie, zawierające interpretery PHP, Node.js, Python, Go, Java oraz popularne bazy danych i serwery (Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached itd.). Główną zaletą ServBay jest gotowość do użycia bez żmudnej konfiguracji – Composer jest skonfigurowany domyślnie, co pozwala bardzo szybko rozpocząć pracę nad projektami Workerman.

W tym poradniku utworzymy kilka podstawowych przykładów, pokazując jak uruchomić w ServBay serwer HTTP, serwer WebSocket oraz serwer TCP z użyciem Workerman.

TIP

Aby ułatwić zarządzanie projektami, ServBay zaleca przechowywanie plików stron lokalnych w następujących lokalizacjach:

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

Wszystkie przykłady ścieżek w tym dokumencie opierają się na tych lokalizacjach.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że spełniasz poniższe wymagania:

1. Zainstalowany i uruchomiony ServBay: Pobierz najnowszą wersję z oficjalnej strony ServBay.
2. PHP aktywowane w ServBay: W panelu sterowania wybierz wersję PHP, której chcesz użyć. Workerman wymaga PHP 5.4 lub nowszego, najlepiej sprawdza się na PHP 7.x lub 8.x.
3. Podstawowa znajomość PHP i obsługi terminala: Musisz znać podstawy PHP oraz potrafić używać poleceń w terminalu.

Instalacja Workerman

1. Dostępność Composer

Composer jest już zintegrowany w ServBay, więc nie trzeba go instalować osobno. Wystarczy uruchomić ServBay oraz włączyć wybraną wersję PHP. Composer automatycznie współpracuje z wybraną wersją PHP w ServBay. Możesz używać Composer w terminalu ServBay lub w zewnętrznym terminalu, jeśli ServBay dodał PHP i Composer do zmiennej PATH systemu.

Sprawdź dostępność Composer poleceniem:

composer -v

Jeśli Composer jest poprawnie zainstalowany, zobaczysz informacje o wersji. W razie problemu – sprawdź czy ServBay działa i czy wybrano wersję PHP.

2. Utwórz folder projektu

Przejdź do zalecanej lokalizacji w ServBay i utwórz nowy katalog projektu:

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

Folder servbay-workerman-demo będzie służyć jako katalog projektu Workerman.

3. Zainstaluj Workerman przez Composer

Będąc w katalogu projektu, zainstaluj bibliotekę Workerman. Jest to rekomendowany sposób, Composer zadba o zależności:

Ścieżka projektu:

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

composer require workerman/workerman

Biblioteka Workerman oraz zależności zostaną pobrane do folderu vendor w Twoim katalogu.

Tworzenie przykładowego serwera HTTP Workerman

Serwer HTTP to najczęstszy przypadek użycia Workerman – idealny do budowania szybkich aplikacji WWW lub API.

Stwórz plik http_server.php (lub inny, np. server.php) w katalogu projektu i dodaj poniższy kod PHP:

<?php
// // Załaduj Composer autoloader, by używać klas Workerman
require __DIR__ . '/vendor/autoload.php';

// // Importuj klasę Worker z Workerman
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// // Utwórz instancję Worker, określając protokół i nasłuchiwany adres
// // 'http://0.0.0.0:8080' oznacza serwer HTTP nasłuchujący na wszystkich interfejsach na porcie 8080
// // 0.0.0.0 umożliwia dostęp lokalny i z sieci LAN; 8080 to numer portu.
$http_worker = new Worker('http://0.0.0.0:8080');

// // Ustaw liczbę procesów Worker
// // Tu: 4 procesy (możesz dostosować liczbę do rdzeni CPU)
$http_worker->count = 4;

// // Definiuj logikę obsługi żądania HTTP (od klienta)
// // $connection: obiekt połączenia, przez który wysyłamy odpowiedź
// // $request: obiekt żądania HTTP, zawiera szczegóły żądania (URL, nagłówki, treść)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // // Wyślij prostą odpowiedź HTTP do klienta
    // // Protokół HTTP Workerman automatycznie obsługuje nagłówki i szczegóły odpowiedzi
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// // Uruchom wszystkie instancje Worker
// // Główna pętla Workerman – proces Worker zaczyna nasłuchiwać portu i zdarzeń
Worker::runAll();

Wyjaśnienie kodu:

• require __DIR__ . '/vendor/autoload.php';: ładuje plik autoload Composer, umożliwiając użycie klas Workerman.
• use Workerman\...;: importuje potrzebne klasy.
• new Worker('http://0.0.0.0:8080'): tworzy instancję Workerman, określając protokół (http) i adres (0.0.0.0:8080).
• $http_worker->count = 4;: liczbę procesów Workerman (więcej procesów = lepsza obsługa wielu połączeń).
• $http_worker->onMessage = function(...) { ... };: callback uruchamiany po odebraniu pełnego żądania HTTP – wysyła odpowiedź do klienta.
• Worker::runAll();: startuje pętlę zdarzeń Workerman, uruchamiając serwer.

Uruchamianie serwera HTTP Workerman

Będąc w katalogu projektu, uruchom serwer HTTP poleceniem:

Ścieżka projektu:

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

php http_server.php start

Tryby pracy:

• Tryb interaktywny (Foreground): Polecenie powyżej uruchamia Workerman w terminalu – wyświetla logi i umożliwia zatrzymanie serwera przez Ctrl+C. Idealne do testów.
• Tryb demonowy (Daemon): W produkcji Workerman powinien pracować jako demon w tle (dodaj -d):

  php http_server.php start -d

  Serwer działa w tle, logi trafiają do pliku (domyślnie w katalogu Workerman lub wskazanej lokalizacji).

Zarządzanie procesami:

Workerman obsługuje wygodne komendy:

• Start: php http_server.php start (interaktywnie) lub php http_server.php start -d (w tle)
• Stop: php http_server.php stop (delikatne wyłączenie po obsłużeniu bieżących żądań)
• Restart: php http_server.php restart
• Reload: php http_server.php reload (miękka aktualizacja kodu – żadne żądanie nie zostaje przerwane, ale pamiętaj o wywołaniach onWorkerStart)
• Status: php http_server.php status (informacje o procesach Workerman, pamięci, liczbie połączeń itd.)

Po uruchomieniu serwera otwórz przeglądarkę i wejdź na http://localhost:8080 lub http://127.0.0.1:8080. Powinieneś zobaczyć komunikat Hello ServBay Workerman HTTP Server!.

Tworzenie serwera WebSocket Workerman

Protokół WebSocket pozwala na trwałe, dwukierunkowe połączenie klient-serwer, świetnie sprawdza się w aplikacjach do komunikacji w czasie rzeczywistym – np. czatach, aktualizacjach giełdowych, grach. Workerman posiada wsparcie dla WebSocket.

1. Kod serwera WebSocket

   Stwórz plik websocket_server.php w katalogu projektu i wklej następujący kod:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // // Utwórz serwer WebSocket nasłuchujący na porcie 8081
   // // 'websocket://0.0.0.0:8081' oznacza serwer WebSocket
   // // Workerman automatycznie obsłuży handshake WebSocket
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // // Liczba procesów: 4
   $ws_worker->count = 4;
   
   // // Callback po nawiązaniu połączenia przez klienta
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "New WebSocket connection from " . $connection->getRemoteIp() . "\n";
   };
   
   // // Callback po odebraniu wiadomości od klienta
   // // $data zawiera odebraną wiadomość (po dekodowaniu)
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Received message: " . $data . "\n";
       // // Odesłanie wiadomości z potwierdzeniem
       $connection->send('ServBay Workerman received: ' . $data);
   };
   
   // // Callback po zamknięciu połączenia
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "WebSocket Connection closed\n";
   };
   
   // // Obsługa błędów (opcjonalnie)
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Error: $code - $msg\n";
   };
   
   
   // // Uruchom wszystkie instancje Worker
   Worker::runAll();

2. Uruchomienie serwera WebSocket

   W katalogu projektu uruchom polecenie:

   php websocket_server.php start

   Możesz dodać -d, by pracował w tle. Po uruchomieniu połącz się z adresem ws://localhost:8081 przy pomocy narzędzi WebSocket (np. przeglądarki, Postman, wtyczka Chrome czy prosta aplikacja JS).

   Przykład testu w konsoli przeglądarki (JavaScript):

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("WebSocket connection opened");
     ws.send("Hello from Browser!"); // Wyślij testową wiadomość
   };
   
   ws.onmessage = function(event) {
     console.log("Message from server:", event.data); // Odbiór wiadomości zwrotnej
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("WebSocket connection closed cleanly, code=" + event.code + " reason=" + event.reason);
     } else {
       console.error("WebSocket connection died");
     }
   };
   
   ws.onerror = function(error) {
     console.error("WebSocket error:", error);
   };
   
   // ws.close(); // Zamknięcie połączenia (opcjonalnie)

   Po nawiązaniu połączenia w terminalu zobaczysz informacje o połączeniach; każda wysłana wiadomość zostanie wyświetlona na serwerze i odesłana do klienta.

Tworzenie serwera TCP Workerman

Workerman sprawdza się także jako serwer TCP obsługujący niestandardowe aplikacje – np. backend do gier, systemy IoT czy autorskie protokoły.

1. Kod serwera TCP

   Stwórz plik tcp_server.php w katalogu projektu i dodaj ten kod:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // // Utwórz serwer TCP nasłuchujący na 8082
   // // 'tcp://0.0.0.0:8082' oznacza serwer TCP
   // // Workerman domyślnie używa protokołu tekstowego (koniec linii '\n')
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // // Liczba procesów: 4
   $tcp_worker->count = 4;
   
   // // Callback po nawiązaniu połączenia klienta
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "New TCP connection from " . $connection->getRemoteIp() . "\n";
       // // Wyślij wiadomość powitalną po połączeniu
       $connection->send("Welcome to ServBay Workerman TCP Server!\n");
   };
   
   // // Callback po odebraniu danych od klienta
   // // $data: odebrane dane TCP po odpowiednim parsowaniu
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Received data: " . $data;
       // // Odesłanie do klienta odebranych danych
       $connection->send('ServBay Workerman received: ' . $data);
   };
   
   // // Callback po zamknięciu połączenia
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "TCP Connection closed\n";
   };
   
   // // Uruchom wszystkie instancje Worker
   Worker::runAll();

2. Uruchomienie serwera TCP

   W katalogu projektu uruchom komendę:

   php tcp_server.php start

   Możesz też dodać -d dla pracy w tle. Po uruchomieniu dołącz do serwera poprzez narzędzia TCP (np. telnet, netcat):

   # telnet
   telnet localhost 8082
   
   # netcat
   nc localhost 8082

   Połączenie zakończy się otrzymaniem komunikatu powitalnego, a każda wpisana linia zostanie odesłana przez serwer.

Ważne wskazówki

• Zajętość portów: Upewnij się, że porty Workerman (np. 8080, 8081, 8082) nie są zajęte przez inne aplikacje lub system. W razie błędu sprawdź zajętość portów poleceniem lsof -i :numer_portu.
• Firewall: Systemowy firewall może blokować dostęp do portów z innych urządzeń. W środowisku lokalnym zwykle nie przeszkadza, jednak jeśli chcesz testować z sieci LAN, sprawdź lub ustaw odpowiednie reguły.
• Niezależność od serwerów webowych ServBay: Workerman działa na własnych portach i w odrębnych procesach – nie jest powiązany z Caddy, Nginx czy Apache w ServBay. Obsługuje własne połączenia bez pośrednictwa tych serwerów, chyba że zdecydujesz się na konfigurację proxy. Workerman najlepiej sprawdza się w aplikacjach wymagających wysokiej liczby połączeń lub pracy w czasie rzeczywistym (np. WebSocket).
• Wersja PHP: Sprawdź, czy wersja PHP w ServBay spełnia minimalne wymagania Workerman. ServBay pozwala szybko przełączać wersje PHP przez panel sterowania.
• Rozszerzenia PHP: Workerman zaleca niektóre rozszerzenia PHP, np. event (umożliwia wyższą wydajność), posix, pcntl (obsługa wielu procesów). ServBay ma większość popularnych rozszerzeń domyślnie aktywnych – w razie kłopotów potwierdź ustawienia w panelu sterowania.
• Logi: W trybie demonowym logi serwera trafiają do pliku – zaglądaj do nich, aby monitorować stan aplikacji i błędy.

Najczęstsze pytania (FAQ)

• Q: Jak zatrzymać serwer Workerman?
  • A: Jeśli uruchomiono w trybie interaktywnym (start), wystarczy Ctrl+C w terminalu. W trybie demonowym (polecenie start -d) użyj w katalogu projektu: php twoj_plik_serwera.php stop.
• Q: Dlaczego serwer Workerman nie uruchamia się?
  • A: Najczęstszą przyczyną jest zajęty port. Sprawdź komunikat błędu w terminalu i spróbuj innego portu, lub zakończ inny program korzystający z tego portu. Polecenie lsof -i :numer_portu podpowie, kto używa portu.
• Q: Czym różni się Workerman od Caddy/Nginx w ServBay? Kiedy ją używać?
  • A: Caddy/Nginx to klasyczne serwery HTTP/HTTPS, współpracujące z PHP-FPM. Workerman to framework asynchroniczny działający jako osobny serwer – obsługuje HTTP, WebSocket, TCP itd., pracuje jako proces rezydujący w pamięci, lepszy do obsługi wysokiej liczby połączeń, WebSocketów, gier czy IoT. Do tradycyjnych stron/REST API lepiej używać Caddy/Nginx; do komunikacji w czasie rzeczywistym – Workerman. Oba rozwiązania można połączyć, np. przez proxy.
• Q: Czy można uruchomić kilka aplikacji Workerman jednocześnie w ServBay?
  • A: Tak, każdy projekt Workerman uruchamiasz w osobnym procesie PHP, na osobnym porcie. Stwórz dedykowany plik startowy dla każdej aplikacji i uruchom polecenia php nazwa_pliku.php start w różnych terminalach (lub w tle), dbając o unikalność portów.

Podsumowanie

Dzięki temu poradnikowi dowiedziałeś się, jak szybko skonfigurować i uruchomić aplikacje Workerman w środowisku ServBay. Workerman, dzięki asynchroniczności i wydajności, pozwala programistom PHP budować nowoczesne aplikacje sieciowe z obsługą wysokiej liczby połączeń i komunikacji w czasie rzeczywistym. ServBay, z gotowym PHP i Composerem, ułatwia start i skraca czas konfiguracji – możesz skupić się na logice biznesowej, nie na środowisku. Niezależnie czy tworzysz szybkie API, czat WebSocket czy serwer TCP, ServBay to doskonały partner lokalny dla Twojego projektu Workerman. Powodzenia w eksplorowaniu możliwości Workerman!