XDebug 3 w PHP – konfiguracja Web, CLI i Postman w PHPStorm dla Linux i Docker

Zdjęcie z debugowania PHPStorm

Xdebug to narzędzie, które zdecydowanie ułatwia pracę PHP Developerowi. Jeszcze jakiś czas temu, jego konfiguracja była nie lada wyczynem, a dinozaury opowiadają że jeszcze wcześniej było to prawie że awykonalne. Trudna konfiguracja i ogromna liczba możliwości to rzeczy, które mogą przytłaczać. Stary dobry var_dump przecież jeszcze żyje.

Nie ma się jednak co zniechęcać. Uruchomienie Xdebuga dla projektu to aktualnie wcale nie taka ciężka sprawa. Trochę trudniejsze może okazać się jego skonfigurowanie w swoim IDE. W PHPStorm jest to stosunkowo proste, ale kiedy zrobi się to już kilka razy. Można to zamknąć w kilku krokach. I właśnie stąd pomysł na ten wpis.

Warto wspomnieć, że konfiguracja dla Windows, czy Mac może się nieco różnić, ale z tego co wiem to nie aż tak bardzo. Większość powinna być tożsama bo w końcu to Docker, ale nie mam w tym temacie doświadczenia, więc to tylko moje przypuszczenia. Jeśli ktoś z Was pracuje na lokalnie zainstalowanym środowisku, a nie korzysta z Dockera to konfiguracja Xdebug będzie jeszcze łatwiejsza. Wiele z tych kroków można pominąć.

Xdebug w Dockerze

Na samym początku trzeba skonfigurować Xdebuga dla PHP. Jeśli chodzi o budowanie obrazu to są to w zasadzie dwie komendy, które wystarczy dorzucić do pliku Dockerfile.

RUN pecl install xdebug \
  && docker-php-ext-enable xdebug

Następnie, po przebudowaniu obrazu, zostaje ustawienie kilku opcji w pliku xdebug.ini. Oczywiście trzeba go zmapować do właściwej lokalizacji w kontenerze. Do tego celu wykorzystane zostaną wolumeny, które konfiguruje się w pliku docker-compose.yml.

volumes:
    - ./.docker/webserver/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Brakuje jeszcze samego pliku .docker/webserver/xdebug.ini, który należy stworzyć i zamieścić w nim następującą konfigurację. Oczywiście plik ten w projekcie można zamieścić pod inną ścieżką – w zależności od potrzeb. To wszystko, nie musicie się zastanawiać nad tym za co odpowiadają poniższe opcje. Jeżeli chcecie korzystać z tego narzędzia w sposób niestandardowy, wtedy warto przejrzeć możliwe ustawienia, bo jest ich dużo więcej.

zend_extension=xdebug

[xdebug]
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal
xdebug.discover_client_host=1
xdebug.idekey=PHPSTORM

I to wszystko – narzędzie powinno już działać w skonfigurowanym środowisku. Teraz połączenie tego z uruchamianiem Xdebuga w PHPStorm.

Xdebug w PHPStorm

Na samym początku trzeba skonfigurować połączenie z serwerem, tak by ustawić CLI Interpreter. Bardzo możliwe, że macie to już zrobione, na przykład na potrzeby uruchamiania PHPUnit, Codesniffer i innych tego typu. Jeśli nie, to spieszę z pomocą. Należy wejść w ustawienia (ctrl + alt + s). Następnie w sekcji PHP, skonfigurować CLI Interpreter – tak jak na załączonych obrazkach.

Zdjęcie konfiguracji PHP Cli PHPStorm
Zdjęcie tworzenia interpretera z docker w PHPStorm

Opcje debugowania można zostawić domyślne, ale w razie czego znajdują się też w ustawieniach, co widać na załączonym obrazku.

Zdjęcie opcji debug w PHPStorm

To już prawie wszystko – jeszcze tylko konfiguracja serwera i najważniejsze, czyli odpowiednie mapowanie ścieżek. Na przykład dla Symfony będzie to wyglądało w ten sposób.

Zdjęcie opcji server w PHPStorm

W tym momencie Xdebug w PHPStorm jest gotowy do używania. Przedstawię trzy sposoby jak go uruchomić, tak by zatrzymał się na Break Point. Pamiętajcie, że zawsze w trakcie procesu debugowania musi być uruchomione nasłuchiwanie.

Zdjęcie menu w PHPStorm

Debugowanie aplikacji przeglądarkowej

Pewnie najczęściej przyjdzie Wam debugować kod korzystając z przeglądarki. Można do URL doklejać odpowiedni parametr, ale ja robię to za pomocą rozszerzenia Xdebug Helper. Wystarczy jeden klik oraz przejście w miejsce, które uruchomi debug i w momencie, gdy jest włączone nasłuchiwanie to Xdebug zatrzyma akcje w wyznaczonym miejscu. W rozszerzeniu trzeba wybrać PHPStorm z możliwych IDE.

Zdjęcie debugowania w PHPStorm

Debugowanie API w Postmanie

Innym miejscem, gdzie czasem warto uruchomić debugowanie jest testowanie API. Do tego celu wykorzystam narzędzie Postman, ale analogicznie można zrobić to w innych. Do adresu URL należy dokleić parametr GET XDEBUG_SESSION_START=PHPSTORM.

Zdjęcie z debugowania PHPStorm

Debugowanie skryptów konsolowych

Inaczej uruchamia się debugowanie z poziomu konsoli. Do tego rodzaju operacji trzeba będzie wcześniej wyeksportować kilka zmiennych. Po pierwsze nazwę serwera skonfigurowanego wcześniej. Ja nazwałem go Docker.

export PHP_IDE_CONFIG="serverName=Docker"

Po drugie kilka opcji konfiguracyjnych, które mają podobne parametry jak te w pliku xdebug.ini.

export XDEBUG_CONFIG="remote_enable=1 remote_mode=req remote_host=127.0.0.1 remote_port=9000 remote_connect_back=0"

W tym momencie podczas nasłuchiwania, uruchomienie dowolnego skryptu konsolowego zatrzyma działanie jest trafi na break point.

Zdjęcie z debugowania PHPStorm

Xdebug – podsumowanie

Na początku cała konfiguracja może wydawać się skomplikowana, ale uwierzcie mi, że jest to dużo przyjemniejsze, niż kiedyś. Po drugie zwrot z używania tego narzędzia jest ogromny. Wszystko jak na dłoni podczas debugowania, a nawet może być fajną opcją do poznania aplikacji. Z Xdebug można robić zaawansowane rzeczy, ale nawet takie zwykłe sprawdzanie aplikacji jest dużo wygodniejsze, niż używanie var_dump().

Krystian Żądło
Programista PHP i właściciel marki Koddlo. Pasjonat czystego kodu i dobrych praktyk programowania obiektowego. Prywatnie fan angielskiej piłki nożnej, dobrego humoru oraz podcastów.