Jak włączyć i skonfigurować moduł Xdebug w ServBay

ServBay to zaawansowane lokalne środowisko do tworzenia aplikacji webowych, które oferuje programistom PHP wstępnie zintegrowane narzędzie Xdebug do debugowania i analizy. Włączenie Xdebuga może znacznie zwiększyć efektywność pracy nad aplikacjami PHP — ułatwia debugging, analizę wydajności i sprawdzanie pokrycia kodu. W tym artykule szczegółowo wyjaśniamy, jak włączyć i skonfigurować Xdebug w ServBay oraz krok po kroku przeprowadzamy przez integrację z najpopularniejszymi środowiskami programistycznymi (IDE).

Przegląd modułu Xdebug

Xdebug to rozbudowane rozszerzenie PHP, zaprojektowane specjalnie do debugowania i analizy kodu PHP. SerwBay zawiera je w instalacji domyślnej, eliminując konieczność ręcznej kompilacji czy instalacji — uruchomienie i konfiguracja jest bardzo prosta.

Najważniejsze funkcje Xdebuga

• Debugowanie z punktami przerwań: Pozwala ustawiać punkty przerwań w konkretnych liniach kodu — wykonanie programu zostaje wtedy zatrzymane, a programista może sprawdzić aktualne wartości zmiennych, stos wywołań itd., wykonując kod krok po kroku.
• Debugowanie krokowe: Umożliwia przechodzenie przez kod linia po linii (Step Over), wchodzenie do funkcji (Step Into) i wychodzenie z funkcji (Step Out), co pozwala na śledzenie przebiegu działania programu.
• Podgląd zmiennych: Wgląd na bieżąco w wartości zmiennych lokalnych i globalnych podczas sesji debugowania.
• Śledzenie stosu: W przypadku błędów i wyjątków prezentuje szczegółowy stos wywołań, ułatwiając szybkie wykrycie źródła problemu.
• Profilowanie wydajności (Profiling): Generuje raporty o wydajności wykonania kodu, co pomaga wykryć wąskie gardła aplikacji.
• Sprawdzanie pokrycia kodu (Code Coverage): Mierzy, jaka część kodu została objęta testami, co umożliwia ocenę jakości testów.

Wersje Xdebuga i mapowanie portów w ServBay

Dla każdego z obsługiwanych przez ServBay wydań PHP wstępnie zainstalowana jest odpowiednia wersja modułu Xdebug. Ważne: każdy wariant PHP wykorzystuje niezależny port do nasłuchiwania przez Xdebug — skorelowany ze swoją wersją. To bardzo istotne podczas konfiguracji debuggera w IDE.

Wersja PHP	Wersja Xdebug	Domyślny port Xdebug
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Zasada portów

Domyślny port nasłuchiwania Xdebug to 39000 + numer podwersji PHP. Przykład: dla PHP 8.3 port to 39000 + 83 = 39083, dla PHP 7.4 jest to 39000 + 74 = 39074. Znajomość tej reguły ułatwia szybkie ustalenie portu Xdebug dla dowolnej wersji PHP.

Jak włączyć moduł Xdebug

Aktywacja Xdebuga w ServBay jest niezwykle prosta — polecamy korzystanie z intuicyjnego interfejsu graficznego (GUI). Możliwe jest także ręczne edytowanie plików konfiguracyjnych.

Włączanie Xdebug przez GUI w ServBay

To najszybszy i najprostszy sposób.

1. Uruchom aplikację ServBay.
2. W lewym panelu nawigacyjnym wybierz sekcję Języki (Languages).
3. Rozwiń sekcję PHP i znajdź wersję PHP, w której chcesz włączyć Xdebug (np. PHP 8.3).
4. Kliknij przycisk Rozszerzenia obok tej wersji PHP.
5. W wyświetlonej liście rozszerzeń znajdź moduł Xdebug.
6. Przestaw przełącznik przy Xdebug z pozycji wyłączonej na włączoną.
7. W razie potrzeby dostosuj parametry.
8. Kliknij przycisk Zapisz na dole interfejsu.
9. ServBay automatycznie zrestartuje proces PHP i załaduje moduł.

Ilustracja: Włączanie Xdebug w sekcji Rozszerzenia

Weryfikacja poprawnego załadowania Xdebuga

Najpewniejszym sposobem jest sprawdzenie konfiguracji PHP za pomocą funkcji phpinfo().

1. W głównym katalogu serwisu ServBay (domyślnie /Applications/ServBay/www) utwórz prosty plik PHP, np. phpinfo.php.
2. W pliku phpinfo.php wpisz poniższy kod:

   <?php
   phpinfo();
   ?>

3. Otwórz plik w przeglądarce, np. https://servbay.demo/phpinfo.php (zamień servbay.demo na własną nazwę domeny skonfigurowaną w ServBay).
4. Na stronie wyjściowej phpinfo wyszukaj frazę "Xdebug". Jeśli moduł działa poprawnie, pojawi się osobna sekcja "Xdebug" z informacjami o wersji i ustawieniach.

Ilustracja: Znalezienie informacji o Xdebug na stronie phpinfo

Konfiguracja Xdebuga w IDE

Aktywacja Xdebuga to dopiero pierwszy etap — aby korzystać z debugowania z poziomu IDE, musisz skonfigurować interpretator PHP, debugger i mapowania serwera. Poniżej instrukcje dla PHPStorm oraz Visual Studio Code (VS Code).

Konfiguracja Xdebug w PHPStorm

PHPStorm oferuje kompleksowe wsparcie dla Xdebuga.

1. Otwórz ustawienia PHPStorm: Uruchom PHPStorm i przejdź do File -> Settings (Windows/Linux) lub PHPStorm -> Preferences (macOS).

2. Dodaj interpreter PHP CLI:

   • Przejdź do Languages & Frameworks -> PHP.
   • W sekcji CLI Interpreter kliknij przycisk ....
   • W nowym oknie kliknij +, aby dodać lokalny interpreter.
   • Wskaż ścieżkę do pliku wykonywalnego PHP z SerwBay, np. /Applications/ServBay/package/php/8.3/8.3.7/bin/php (numery mogą się różnić w zależności od aktualnej wersji — wybierz swoją instalację ServBay).
   • PHPStorm sam wykryje wersję i rozszerzenia (w tym Xdebuga).
   • Kliknij OK, aby zapisać. Ilustracja: Dodawanie interpretera PHP CLI z SerwBay w PHPStorm

3. Ustaw parametry debugowania Xdebug:

   • Przejdź do Languages & Frameworks -> PHP -> Debug.
   • W sekcji Xdebug ustaw Debug Port zgodnie z portem podanym dla swojej wersji PHP w ServBay (np. dla PHP 8.3 to 39083). Port musi się zgadzać z ustawieniem xdebug.client_port.
   • Zaznacz opcję Can accept external connections.
   • Kliknij Apply i następnie OK, aby zapisać. Ilustracja: Konfiguracja portu Xdebug w PHPStorm

4. Skonfiguruj mapowania serwera:

   • Przejdź do Languages & Frameworks -> PHP -> Servers.
   • Kliknij +, by dodać nowy serwer.
   • Nazwij serwer (np. ServBay Localhost).
   • Wpisz Host — adres domeny dla wybranego projektu w ServBay (np. servbay.demo).
   • Ustaw Port — najczęściej 443 (HTTPS) lub 80 (HTTP).
   • Ustaw typ debuggera na Xdebug.
   • Zaznacz pole Use path mappings.
   • Ustal mapowanie ścieżek lokalnych (Absolute path to local source) do ścieżek serwera (Absolute path on the server). Jeśli projekt położony jest w /Applications/ServBay/www/myproject i dostępny pod adresem https://servbay.demo/, to lokalna ścieżka /Applications/ServBay/www/myproject powinna być zmapowana na /. Jeśli używasz subdomeny https://myproject.servbay.demo/ dla katalogu /Applications/ServBay/www/myproject, również lokalna ścieżka /Applications/ServBay/www/myproject powinna być mapowana na /. Poprawność mapowania jest kluczowa dla działania debugowania Xdebug!
   • Kliknij OK, aby zatwierdzić. Ilustracja: Konfiguracja serwera i mapowania ścieżek w PHPStorm

5. Rozpoczęcie debugowania:

   • Otwórz plik projektu PHP w PHPStorm.
   • Kliknij lewą stronę obok numeru linii, by dodać punkt przerwania (czerwone kółko).
   • Kliknij ikonę „Start Listening for PHP Debug Connections” na pasku narzędzi (ikona z robaczkiem). Powinna się podświetlić na zielono — oznacza to, że PHPStorm nasłuchuje połączeń Xdebug.
   • Otwórz stronę swojej aplikacji w przeglądarce (np. https://servbay.demo/index.php).
   • Jeśli wszystko skonfigurowane poprawnie, Xdebug połączy się z PHPStormem i wykona zatrzymanie na wybranym punkcie przerwania. Ilustracja: Włączanie nasłuchiwania Xdebug w PHPStorm

Konfiguracja Xdebug w Visual Studio Code (VS Code)

VS Code to jeden z najpopularniejszych edytorów kodu, obsługujący debugowanie Xdebug za pomocą dodatkowej wtyczki.

1. Zainstaluj rozszerzenie PHP Debug:

   • Otwórz VS Code.
   • Przejdź do widoku rozszerzeń (Ctrl+Shift+X lub Cmd+Shift+X).
   • Wyszukaj „PHP Debug” i zainstaluj rozszerzenie autorstwa Felix Becker.

2. Skonfiguruj launch.json:

   • Otwórz folder projektu PHP.
   • Przejdź do widoku Run and Debug (Ctrl+Shift+D lub Cmd+Shift+D).
   • Kliknij ikonę koła zębatego na górze, wybierz „PHP”. Utworzony zostanie plik launch.json w folderze .vscode w katalogu głównym projektu.
   • Edytuj launch.json — upewnij się, że wartość port odpowiada portowi Xdebug ustawionemu dla wybranej wersji PHP (np. dla PHP 8.3 to 39083).
   • Ustaw mapowanie ścieżek (Path Mapping): To klucz do poprawnego debugowania w VS Code! W pliku launch.json znajdź (lub dodaj) sekcję pathMappings. Pozwala ona połączyć ścieżkę projektu po stronie serwera z lokalną na Twoim komputerze.

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // Dostosuj port zgodnie z wersją PHP
                 "pathMappings": {
                     // Mapowanie ścieżek serwera ServBay na lokalny system plików
                     // Jeśli Twój projekt jest w /Applications/ServBay/www/myproject
                     // i dostępny przez https://servbay.demo/, serwerowy '/' odpowiada lokalnemu katalogowi projektu
                     "/": "${workspaceRoot}"
                     // Gdy projekt jest pod /Applications/ServBay/www/myproject
                     // i dostępny przez https://myproject.servbay.demo/ (subdomena jako podkatalog)
                     // analogicznie '/' po stronie serwera = katalog lokalny
                     // "/": "${workspaceRoot}" // również poprawne
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // Dostosuj port zgodnie z wersją PHP
             }
         ]
     }

     Dostosuj ustawienia pathMappings do struktury swojego projektu i konfiguracji stron w ServBay. ${workspaceRoot} zazwyczaj jest katalogiem głównym otwartego projektu w VS Code.

3. Rozpoczęcie debugowania:

   • Otwórz plik PHP w VS Code.
   • Kliknij po lewej stronie numeru linii, aby dodać punkt przerwania (czerwone kółko).
   • Przejdź do widoku debugowania (Ctrl+Shift+D lub Cmd+Shift+D).
   • Wybierz z listy konfigurację "Listen for Xdebug".
   • Kliknij zielony przycisk uruchomienia debugowania. Pasek stanu VS Code zmieni kolor na pomarańczowy — oznacza to, że nasłuchuje połączenia Xdebug.
   • Otwórz swoją aplikację w przeglądarce. Jeśli wszystko ustawione jest poprawnie, Xdebug połączy się z VS Code i zatrzyma się na wybranym punkcie przerwania.

Najczęstsze pytania (FAQ)

• P: Xdebug nie pojawia się na stronie phpinfo()?

  • O: Sprawdź, czy Xdebug został włączony przez GUI ServBay lub ręczną edycję pliku xdebug.ini.
  • Upewnij się, że uruchomiono ponownie odpowiedni serwis PHP.
  • Zweryfikuj ścieżkę do pliku xdebug.ini i czy linia zend_extension = xdebug.so nie jest zakomentowana.
  • Przejrzyj plik logów ServBay (/Applications/ServBay/logs/php/<version>/error.log), by wykryć ewentualne błędy ładowania Xdebug.

• P: Program nie zatrzymuje się na punktach przerwania ustawionych w IDE?

  • O: Upewnij się, że Twoje IDE faktycznie nasłuchuje połączeń Xdebug (zielony robaczek w PHPStorm, pomarańczowy pasek w VS Code).
  • Sprawdź, czy skonfigurowany port Xdebug w IDE odpowiada wartości xdebug.client_port oraz domyślnemu portowi dla danej wersji PHP.
  • Zweryfikuj mapowanie ścieżek (Path Mapping) w IDE — poprawność mapowania ścieżek serwera na lokalny system plików jest krytyczna!
  • Sprawdź ustawienia zapory sieciowej, czy port nasłuchu Xdebug nie jest blokowany (domyślnie seria 390xx).
  • Jeśli w xdebug.ini ustawiono xdebug.start_with_request=trigger, upewnij się, że żądanie (np. za pośrednictwem dodatku Xdebug Helper w przeglądarce lub manualnie przez ?XDEBUG_TRIGGER=1 w URL) faktycznie aktywuje sesję debugowania.

• P: Połączenie z Xdebug jest zrywane po krótkim czasie?

  • O: Zweryfikuj ustawienia xdebug.remote_autostart lub xdebug.start_with_request w pliku xdebug.ini. Wartość yes może powodować uruchamianie debugera przy każdym żądaniu — lepiej wybrać tryb trigger.
  • Sprawdź również ustawienia timeoutu debugera po stronie IDE.

Podsumowanie

Dzięki wstępnej integracji i uproszczonej konfiguracji ServBay znacząco obniża barierę wejścia w korzystanie z Xdebug dla programistów PHP. Niezależnie od tego, czy preferujesz wygodny interfejs graficzny, czy ręczną edycję plików konfiguracyjnych, możesz szybko aktywować Xdebug w wybranej wersji PHP działającej w ServBay. Łącząc tę funkcjonalność z zaawansowanymi możliwościami debugowania PHPStorma, VS Code i innych popularnych IDE — zyskujesz potężny zestaw narzędzi do efektywnego debugowania, optymalizacji wydajności i kontroli jakości kodu. Opanowanie współpracy ServBay z Xdebugiem znacznie usprawni Twój workflow programistyczny PHP.