Konfiguracja Xdebug w PHPStorm

Debugowanie jest jednym z najważniejszych procesów w programowaniu. Za pomocą debuggera można zobaczyć, co dzieje się w programie, jakie funkcje są wykonywane, co jest przechowywane w zmiennych, a także wykonać wszystko krok po kroku i zrozumieć dokładnie, w której linii i przy jakich wartościach zmiennych wystąpił błąd.

Na przykład debugger Xdebug jest używany dla PHP, PHPStorm jest jednym z najpopularniejszych środowisk programistycznych. Następnie zobaczmy, jak skonfigurować Xdebug w PhpStorm do debugowania na komputerze lokalnym i w Dockerze.

Konfiguracja XDEBUG w PHPSTORM

Porozmawiajmy o tym, jak debugowanie odbywa się na lokalnym serwerze.

Przyjrzyjmy się całemu procesowi na przykładzie Ubuntu i interpretera PHP skonfigurowanego z Apache. W przypadku innych konfiguracji ścieżki plików mogą być inne, ale cel jest ten sam. Debugger Xdebug pozwala na wstrzymanie wykonywania kodu, podgląd stosu wywołań i zawartości zmiennych. Jego jedyną wadą jest brak wygodnego interfejsu sterowania. IDE są zwykle używane do zarządzania debugowaniem. Ale IDE nie może powiedzieć debuggerowi, aby rozpoczął debugowanie, ponieważ jest odpowiedzialny tylko za kod. W tym celu potrzebne jest rozszerzenie przeglądarki Debug Helper, za pomocą którego można włączyć tryb debugowania.

Najpierw należy zainstalować Xdebug. Aby to zrobić, wykonaj:

$ sudo apt install xdebug

Po zakończeniu procesu instalacji Xdebug należy skonfigurować program tak, aby po uruchomieniu sesji debugowania próbował połączyć się z naszym IDE w celu kontroli debugowania. W tym celu należy dodać te linie do pliku /etc/php/7.4/apache2/conf.d/20-xdebug.ini w wersji Xdebug 2:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

W przypadku nowszej wersji najlepiej jest użyć innego formatu:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Przyjrzyjmy się bliżej ustawieniom. Pierwszy parametr xdebug.mode - tryb debugowania, możliwe opcje to:

• develop - włącza wyprowadzanie dodatkowych informacji, nadpisuje var_dump;

• debug - tryb wykonywania kodu linia po linii, jest to tryb, którego potrzebujemy w tym przypadku;

• profile - profilowanie;

• trace -śledzenie wykonywania programu.

Kilka trybów jest włączonych jednocześnie, gdy są wymienione w przecinkach. Druga linia xdebug.start_with_request definiuje sposób uruchamiania debuggera dla trybów debug, trace i podobnych:

• yes - zawsze, podczas uruchamiania skryptów php;
• no - uruchamiany tylko z kodu przy użyciu specjalnych funkcji;
• trigger - na żądanie, przy użyciu specjalnej zmiennej w $_ENV, $_POST, $COOKIE lub innej tablicy. Ta opcja najlepiej pasuje w tym przypadku, aby debugger nie uruchamiał się, gdy nie jest to konieczne.

Trzeci xdebug.discover_client_host jest ustawiony na true, w którym to przypadku xdebug próbuje połączyć się z hostem przekazanym w nagłówku HTTP_X_FORWARDED_FOR. Ponieważ host jest określony w następnej linii, ta funkcja nie jest potrzebna w tym przypadku. Następnie host klienta, z którym należy się połączyć w celu kontroli debugowania, to 127.0.0.1 i port 9000. Jest to domyślny port używany obecnie w PhpStorm. Po zapisaniu ustawień należy zrestartować Apache za pomocą specjalnego polecenia:

$ sudo systemctl restart apache2

Następnie należy skonfigurować PhpStorm. Należy uruchomić program, a następnie otworzyć menu Run -> Edit Configurations. Pojawi się okno, w którym należy skonfigurować debugger.

Kliknij przycisk + i wybierz PHP Remote Debugger z listy, która się otworzy:

Nie zmieniaj niczego w ustawieniach, po prostu określ nazwę tej metody debugowania. Jeśli nie określisz serwera, z którego będą oczekiwane połączenia, wszystkie połączenia będą akceptowane.

Jeśli chcesz zmienić port, z którym Xdebug będzie się łączył, otwórz Plik -> Ustawienia -> PHP -> Debug -> DBGp Proxy. Tutaj możesz określić żądany port.

Można powiedzieć, że teraz IDE jest gotowe. Teraz kliknij na błąd na górnym pasku narzędzi. Program zacznie czekać na połączenie debuggera, a my umieścimy w kodzie kilka punktów przerwania, klikając przed linią z kodem:

Teraz pozostaje już tylko skonfigurować przeglądarkę.W przypadku Chrome można pobrać specjalne rozszerzenie. Zainstaluj je i otwórz stronę, którą chcesz debugować. Kliknij ikonę rozszerzenia i wybierz Debug. Ikona rozszerzenia zmieni kolor na zielony:

Odśwież stronę i wróć do PHPStorm. Jeśli wszystko zostało wykonane poprawnie, rozpocznie się sesja debugowania. Przy pierwszym uruchomieniu program może poprosić o skonfigurowanie lokalnych ścieżek plików tak, aby odpowiadały ścieżkom plików zdalnych. W przypadku lokalnego serwera nie trzeba niczego konfigurować, wystarczy kliknąć Accept:

Następnie debugger zatrzyma wykonywanie w wybranym punkcie przerwania, a w programie pojawi się interfejs debugowania:

Zobaczmy teraz, jak skonfigurować Xdebug PhpStorm i Docker.

Debugowanie PHP w DOCKER

Docker może być nieco skomplikowany. Ponieważ debugger musi łączyć się z samym IDE, konieczne jest przekierowanie hosta do kontenera. W systemie Windows można to zrobić za pomocą adresu host.docker.internal. Ale w systemie Linux nie dzieje się to domyślnie. Aby dodać taki adres, należy dodać następujące linie do docker-compose:

extra_hosts:

host.docker.internal: host-gateway

Używamy następującej struktury katalogów:

Minimalny wymagany plik docker-compose.yaml będzie wyglądał następująco:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Po prostu deklarujemy dwa kontenery, nginx i php-fpm. Nie wprowadzamy żadnych zmian w pierwszym z nich, więc możemy po prostu wziąć oficjalny obraz, zamontować folder źródłowy, plik konfiguracyjny i przekierować port. W drugim kontenerze konieczne jest zainstalowanie i skonfigurowanie Xdebug, więc będzie on musiał zostać zbudowany na podstawie oficjalnego kontenera php. Dla tego samego kontenera konieczne jest określenie dyrektywy extra_hosts, bez niej nic nie będzie działać. Konfiguracja Nginx jest również dość standardowa:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

W ten sposób konfiguruje się przetwarzanie skryptów PHP w kontenerze php-fpm i przekierowuje nieistniejące adresy URL do index.php, co jest dość standardowe dla wielu frameworków i CMS-ów. W pliku Dockerfile kontenera php-fpm wygląda to następująco:

Zainstaluj xdebug za pomocą pecl, a następnie skopiuj jego plik konfiguracyjny do kontenera. Plik:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

Xdebug 3 dla PHP 8 jest zainstalowany w kontenerze, ponieważ stara wersja nie działa już z tą wersją języka, więc używana jest nowa składnia konfiguracji. Dobrze host, host.docker.internal, który wcześniej był przepisany w docker-compose.yaml. Konfiguracja xdebug PHPStorm docker jest teraz zakończona. Następnie można uruchomić projekt:

docker-compose up --build

Teraz, podobnie jak w poprzedniej opcji, można włączyć tryb debugowania w przeglądarce, odświeżyć stronę, a debugger pomyślnie połączy się z IDE, mimo że jest uruchomiony w Dockerze