Tworzenie i uruchamianie aplikacji Workerman w ServBay

Przegląd

Ten dokument ma na celu poprowadzić użytkowników ServBay przez proces szybkiego budowania i uruchamiania wysokowydajnych, asynchronicznych aplikacji sieciowych PHP z użyciem Workerman w środowisku deweloperskim macOS. ServBay dostarcza gotowe środowisko zintegrowane z Composerem, dzięki czemu konfiguracja Workerman jest banalnie prosta. Workerman to potężna biblioteka PHP, idealna do budowy usług sieciowych wymagających obsługi dużej liczby równoczesnych połączeń – takich jak serwer WWW, komunikator czasu rzeczywistego czy backend dla gier.

Czym jest Workerman?

Workerman to napisany wyłącznie w PHP, otwartoźródłowy framework asynchroniczny do wydajnej komunikacji sieciowej. Wykorzystuje EventLoop, czyli mechanizm pętli zdarzeń, realizując asynchroniczne i nieblokujące operacje I/O. Dzięki temu efektywnie obsługuje bardzo wiele połączeń jednocześnie. W przeciwieństwie do tradycyjnej architektury PHP (Apache/Nginx + PHP-FPM), aplikacje Workerman działają stale w pamięci, nasłuchując na wybranym porcie i obsługując połączenia bezpośrednio, eliminując koszt ponownego uruchamiania procesów dla każdego żądania i znacząco zwiększając wydajność oraz przepustowość.

Dzięki Workerman możesz łatwo zbudować:

• Wysokowydajne serwery HTTP – mogą nawet zastąpić Apache/Nginx do prostych dynamicznych lub statycznych zadań.
• Serwery WebSocket do czatów, transmisji danych czy aplikacji czasu rzeczywistego.
• Serwery TCP/UDP obsługujące własne protokoły.
• Narzędzia konsolowe, zadania cykliczne, mikroserwisy i inne.

Kluczowe cechy i zalety Workerman

• Wydajność: Działanie oparte o zdarzenia i asynchroniczne I/O umożliwia obsługę ogromnej liczby połączeń z wysoką wydajnością.
• Obsługa wielu protokołów: Natywna obsługa HTTP, WebSocket, TCP, UDP oraz łatwość implementowania własnych protokołów.
• Łatwość użycia: Przejrzyste API i niska bariera wejścia dla programistów PHP, minimalizująca złożoność programowania asynchronicznego.
• Elastyczność: Pełne wsparcie dla wielu procesów, wykorzystanie wielordzeniowych CPU, łatwa integracja pakietów Composer i innych bibliotek PHP.
• Zgodność z ekosystemem PHP: Workerman to biblioteka PHP, więc korzysta z pełnych możliwości Composer i istniejących rozszerzeń ekosystemu.
• Tryb demona: Obsługuje działanie w tle jako demon, zapewniając stabilność i wysoką dostępność w środowisku produkcyjnym.

Workerman otwiera przed programistami PHP nowe możliwości tworzenia aplikacji sieciowych o wysokiej wydajności, w czasie rzeczywistym i gotowych na wysoką skalę ruchu.

Tworzenie środowiska Workerman w ServBay

ServBay to narzędzie lokalnego środowiska deweloperskiego stworzone specjalnie z myślą o web developerach. Zawiera wbudowane środowiska takie jak PHP, Node.js, Python, Go, Java, a także serwery i bazy danych (Caddy, Nginx, Apache, MySQL, PostgreSQL, MongoDB, Redis, Memcached). Największą zaletą ServBay jest koncepcja „gotowy do użycia” – wszystko jest zainstalowane i skonfigurowane, w tym Composer. To sprawia, że uruchomienie projektu Workerman jest szybkie i bezproblemowe.

W tej instrukcji zbudujesz kilka podstawowych przykładów, pokazujących jak stworzyć i uruchomić aplikacje Workerman w ServBay: prosty serwer HTTP, serwer WebSocket oraz serwer TCP.

TIP

Dla łatwego zarządzania ServBay zaleca, aby wszystkie lokalne projekty znajdowały się w katalogu /Applications/ServBay/www. Wszystkie ścieżki w tej dokumentacji odnoszą się właśnie do tej lokalizacji.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że:

1. ServBay jest zainstalowany i działa poprawnie: Pobierz najnowszą wersję ze strony ServBay.
2. PHP w ServBay jest aktywowane: W panelu sterowania ServBay upewnij się, że wybrana wersja PHP jest włączona. Workerman wymaga PHP w wersji co najmniej 5.4 (zalecane 7.x lub 8.x dla maksymalnej wydajności).
3. Masz podstawową wiedzę o PHP i konsoli: Powinieneś znać podstawy składni PHP i umieć korzystać z terminala.

Instalacja Workerman

1. Upewnij się, że Composer jest dostępny

Composer jest preinstalowany w ServBay – nie musisz niczego instalować osobno. Upewnij się, że ServBay oraz wybrana wersja PHP są uruchomione. Composer jest automatycznie skonfigurowany dla wybranej wersji PHP. Możesz korzystać z terminala ServBay lub zewnętrznego terminala (jeśli ServBay dodał ścieżki do PATH systemu).

Sprawdź dostępność Composera komendą:

composer -v

Jeśli Composer jest poprawnie zainstalowany w środowisku ServBay, zobaczysz informacje o wersji. W razie braku polecenia sprawdź, czy ServBay jest uruchomiony i czy PHP jest aktywowane.

2. Utwórz katalog projektu

Przejdź do katalogu rekomendowanego przez ServBay i utwórz nowy folder projektu:

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

Stworzony folder servbay-workerman-demo będzie przechowywać pliki projektu Workerman.

3. Instalacja Workerman przez Composer

W katalogu projektu (/Applications/ServBay/www/servbay-workerman-demo) zainstaluj Workerman:

composer require workerman/workerman

Composer automatycznie pobierze Workerman i wszystkie zależności do katalogu vendor.

Pisanie serwera HTTP Workerman

Serwer HTTP to jeden z najczęstszych przypadków użycia Workerman – idealny do wydajnych API lub webserwisów.

W folderze projektu utwórz plik http_server.php (lub np. server.php):

<?php
// Załaduj autoloader Composera, by korzystać z klas Workerman
require __DIR__ . '/vendor/autoload.php';

// Importuj klasy Workerman
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
use Workerman\Protocols\Http\Response;

// Utwórz instancję Worker nasłuchującą na HTTP://0.0.0.0:8080 (port 8080 na wszystkich interfejsach sieciowych)
// 0.0.0.0 pozwala na dostęp zarówno lokalnie, jak i z LAN; port 8080 to numer, na którym odbierane są połączenia
$http_worker = new Worker('http://0.0.0.0:8080');

// Ustaw liczbę procesów Worker
// Wartość 4 oznacza uruchomienie 4 niezależnych procesów PHP do obsługi żądań; możesz ustawić zgodnie z liczbą rdzeni CPU
$http_worker->count = 4;

// Zdefiniuj co zrobić po odebraniu żądania HTTP od klienta
// $connection to obiekt połączenia do klienta (do wysyłania odpowiedzi)
// $request to obiekt żądania HTTP (zawiera dane URL, nagłówki, body itd.)
$http_worker->onMessage = function(TcpConnection $connection, Request $request) {
    // Wyślij prostą odpowiedź HTTP jako tekst
    // Protokół HTTP Workerman automatycznie zajmuje się nagłówkami itd.
    $connection->send(new Response(200, [], 'Hello ServBay Workerman HTTP Server!'));
};

// Uruchom pętlę główną Workerman i wszystkie utworzone Worker Instance
Worker::runAll();

Objaśnienie kodu:

• require __DIR__ . '/vendor/autoload.php';: ładuje autoloader Composera i umożliwia korzystanie z bibliotek Workerman.
• use Workerman\...;: importuje wymagane klasy.
• new Worker('http://0.0.0.0:8080'): tworzy nowy Worker nasłuchujący na określonym protokole i porcie.
• $http_worker->count = 4;: liczba procesów Workerman – więcej procesów = lepsza obsługa wielu żądań na raz (zwłaszcza na wielordzeniowych CPU).
• $http_worker->onMessage = function(...) { ... }: callback do obsługi każdego kompletnego żądania HTTP – umożliwia dostęp do połączenia i żądania.
• Worker::runAll();: uruchamia główną pętlę i umożliwia obsługę połączeń.

Uruchamianie serwera HTTP Workerman

W katalogu projektu (/Applications/ServBay/www/servbay-workerman-demo), uruchom serwer HTTP poleceniem:

php http_server.php start

Tryby uruchamiania:

• Tryb pierwszy plan (Foreground): Po uruchomieniu komendy Workerman działa w terminalu, pokazuje logi i status. Zatrzymanie przez Ctrl+C. Idealny do developmentu.
• Tryb demona (backgound): W produkcji zwykle korzysta się z trybu demona dzięki opcji -d:

  php http_server.php start -d

  Proces działa w tle, wyjście przekierowywane jest do logów Workermana (domyślnie w katalogu projektu lub ustawionej lokalizacji).

Zarządzanie procesem:

Przydatne komendy Workerman:

• Start: php http_server.php start (terminal) lub php http_server.php start -d (w tle)
• Stop: php http_server.php stop (po eleganckim zakończeniu żądań)
• Restart: php http_server.php restart (najpierw stop, potem start)
• Reload (łagodny restart): php http_server.php reload (do aktualizacji kodu bez przerywania usług, szczególnie dla callbacków typu onWorkerStart zalecana ostrożność)
• Status: php http_server.php status (wyświetla status, stan pamięci, liczby połączeń itd.)

Po starcie serwera odwiedź w przeglądarce http://localhost:8080 lub http://127.0.0.1:8080 – powinieneś zobaczyć komunikat Hello ServBay Workerman HTTP Server!.

Tworzenie serwera WebSocket w Workerman

Protokół WebSocket pozwala na stabilne, dwukierunkowe połączenie klient-serwer – idealny do czatów, push notification, gier itp. Workerman wspiera go natywnie.

1. Kod serwera WebSocket

   W katalogu projektu stwórz plik websocket_server.php z poniższą zawartością:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Utwórz instancję serwera WebSocket nasłuchującą na porcie 8081
   // 'websocket://0.0.0.0:8081' – Workerman automatycznie realizuje handshake WebSocket
   $ws_worker = new Worker('websocket://0.0.0.0:8081');
   
   // Uruchom 4 procesy
   $ws_worker->count = 4;
   
   // Obsługa nowego połączenia
   $ws_worker->onConnect = function(TcpConnection $connection) {
       echo "Nowe połączenie WebSocket z adresu " . $connection->getRemoteIp() . "\n";
   };
   
   // Obsługa otrzymania wiadomości
   $ws_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Otrzymano wiadomość: " . $data . "\n";
       // Odesłanie odpowiedzi do klienta
       $connection->send('ServBay Workerman otrzymał: ' . $data);
   };
   
   // Obsługa rozłączenia klienta
   $ws_worker->onClose = function(TcpConnection $connection) {
       echo "Połączenie WebSocket zakończone\n";
   };
   
   // Obsługa błędów
   $ws_worker->onError = function(TcpConnection $connection, $code, $msg) {
       echo "Błąd: $code - $msg\n";
   };
   
   // Uruchom Workermana
   Worker::runAll();

2. Uruchom serwer WebSocket

   W katalogu projektu uruchom serwer komendą:

   php websocket_server.php start

   Do pracy w tle skorzystaj z -d. Następnie użyj narzędzia klienckiego WebSocket lub przeglądarki:

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

   var ws = new WebSocket("ws://localhost:8081");
   
   ws.onopen = function(event) {
     console.log("Połączenie WebSocket nawiązane");
     ws.send("Wiadomość z przeglądarki!");
   };
   
   ws.onmessage = function(event) {
     console.log("Wiadomość od serwera:", event.data);
   };
   
   ws.onclose = function(event) {
     if (event.wasClean) {
       console.log("Połączenie WebSocket zamknięte poprawnie, kod=" + event.code + " powód=" + event.reason);
     } else {
       console.error("Nieoczekiwane zakończenie połączenia WebSocket");
     }
   };
   
   ws.onerror = function(error) {
     console.error("Błąd WebSocket:", error);
   };
   
   // Zamknięcie połączenia (opcjonalnie)
   // ws.close();

   Po poprawnym połączeniu terminal pokaże informacje o połączeniu, a przeglądarka otrzyma odpowiedź echo od serwera.

Tworzenie serwera TCP w Workerman

Workerman umożliwia też tworzenie serwerów TCP, obsługujących niestandardowe protokoły – świetne rozwiązanie dla backendów gier, IoT czy własnych usług komunikacyjnych.

1. Kod serwera TCP

   Stwórz plik tcp_server.php z poniższą treścią:

   <?php
   require __DIR__ . '/vendor/autoload.php';
   
   use Workerman\Worker;
   use Workerman\Connection\TcpConnection;
   
   // Utwórz serwer TCP nasłuchujący na porcie 8082
   // 'tcp://0.0.0.0:8082' – domyślny protokół to tekstowy (z '\n' na końcu), możesz ustawić własny
   $tcp_worker = new Worker('tcp://0.0.0.0:8082');
   
   // Uruchom 4 procesy
   $tcp_worker->count = 4;
   
   // Połączony klient
   $tcp_worker->onConnect = function(TcpConnection $connection) {
       echo "Nowe połączenie TCP z adresu " . $connection->getRemoteIp() . "\n";
       // Powitanie klienta
       $connection->send("Witamy w ServBay Workerman TCP Server!\n");
   };
   
   // Otrzymanie danych od klienta
   $tcp_worker->onMessage = function(TcpConnection $connection, $data) {
       echo "Otrzymano dane: " . $data;
       // Odesłanie echo do klienta
       $connection->send('ServBay Workerman otrzymał: ' . $data);
   };
   
   // Rozłączenie
   $tcp_worker->onClose = function(TcpConnection $connection) {
       echo "Połączenie TCP zakończone\n";
   };
   
   // Start Workerman
   Worker::runAll();

2. Uruchamianie serwera TCP

   W katalogu projektu uruchom polecenie:

   php tcp_server.php start

   Możesz też uruchomić w trybie demona (-d). Po starcie użyj narzędzi klienckich takich jak telnet lub nc:

   # telnet
   telnet localhost 8082
   
   # lub nc (netcat)
   nc localhost 8082

   Po nawiązaniu połączenia otrzymasz powitanie serwera. Wpisując tekst (zakończony Enterem), zobaczysz echo od Workermana.

Wskazówki i dobre praktyki

• Zajętość portu: Upewnij się, że porty (w przykładach: 8080, 8081, 8082) są wolne – nie może korzystać z nich żaden inny proces z macOS lub ServBay. W razie konfliktu Workerman zgłosi błąd. Sprawdź zajętość komendą lsof -i :numer_portu.
• Firewall: Zintegrowana zapora sieciowa macOS może blokować dostęp do portów z zewnętrznych urządzeń. Lokalnie to nie problem, ale przy testach LAN skonfiguruj reguły firewall.
• Workerman vs. serwery WWW ServBay: Workerman działa niezależnie na własnych portach i nie jest związany z serwerami Caddy lub Nginx uruchamianymi przez ServBay. Aplikacje w Workerman zwykle nie korzystają z proxy tych serwerów, chyba że ustawisz reverse proxy specjalnie. Workerman jest idealny do obsługi połączeń długotrwałych i wysokowydajnych (np. WebSockety). Standardowy serwer (Caddy/Nginx) obsługuje klasyczne żądania HTTP.
• Wersja PHP: Dopilnuj, by wersja PHP w ServBay spełniała minimalne wymagania Workerman. ServBay wspiera wiele wersji PHP; wybierz odpowiednią w panelu ServBay.
• Rozszerzenia PHP: Workerman działa najlepiej z rozszerzeniami event, posix, pcntl (służą one m.in. do obsługi wielu procesów). ServBay domyślnie aktywuje najczęściej używane rozszerzenia, ale sprawdź konfigurację, jeśli napotkasz błędy.
• Logi: W trybie demona logi Workerman są zapisywane do plików – regularnie je przeglądaj, by monitorować stan aplikacji.

Najczęstsze pytania (FAQ)

• Q: Jak zatrzymać serwer Workerman?
  • A: Jeśli działa na pierwszym planie (start), zatrzymasz go przez Ctrl+C w terminalu. Jeśli działa w tle (start -d), zatrzymasz poleceniem php nazwa_pliku_serwera.php stop w katalogu projektu.
• Q: Dlaczego serwer Workerman nie chce się uruchomić?
  • A: Najczęściej winny jest zajęty port. Sprawdź komunikat błędu – zwykle podpowie, który port jest zajęty. Zmień port lub zwolnij go inne programy. Użyj lsof -i :numer_portu by znaleźć winny proces.
• Q: Jaka jest różnica między Caddy/Nginx ServBay a Workermanem?
  • A: Caddy i Nginx to tradycyjne serwery WWW do klasycznych żądań HTTP/HTTPS, często używane z PHP-FPM (każde żądanie = nowy proces). Workerman to asynchroniczny framework, sam działa jako serwer HTTP, obsługuje również WebSocket, TCP i inne protokoły, stale rezyduje w pamięci, wysoce skalowalny i stworzony z myślą o połączeniach długoterminowych czy wysokiej liczbie żądań w czasie rzeczywistym. Dobór zależy od rodzaju aplikacji: zwykła strona/REST API – Caddy/Nginx; czat, push, backend gier – Workerman. Możliwa jest też współpraca (np. proxy Caddy/Nginx => Workerman dla wybranych endpointów).
• Q: Czy mogę uruchomić kilka aplikacji Workerman w ServBay równocześnie?
  • A: Tak, każda aplikacja Workerman powinna mieć osobny plik uruchomieniowy i nasłuchiwać na innym porcie. W terminalu możesz równolegle uruchamiać wiele takich serwerów, byle zadbać o unikalność portów.

Podsumowanie

Dzięki temu przewodnikowi poznałeś cały proces budowy i uruchamiania aplikacji Workerman w ServBay – wydajnym środowisku deweloperskim. Workerman, dzięki swojej asynchroniczności i wysokiej wydajności, otwiera przed programistami PHP drzwi do nowoczesnych, wysokoskalowalnych aplikacji sieciowych. Dzięki gotowemu środowisku ServBay z preinstalowanym Composerem i PHP możesz skupić się na kodowaniu logiki aplikacji, a nie na żmudnej konfiguracji środowiska. Niezależnie czy tworzysz szybki serwis WWW, czy aplikację czasu rzeczywistego z WebSocket – ServBay i Workerman to idealne połączenie dla lokalnej pracy deweloperskiej na macOS. Powodzenia w odkrywaniu możliwości Workerman!