Konfigurace Xdebug v aplikaci PHPStorm

Ladění je jedním z nejdůležitějších procesů v programování. Pomocí ladicího programu můžete sledovat, co se v programu děje, jaké funkce se vykonávají, co je uloženo v proměnných, a také vše krok za krokem provádět a přesně pochopit, na kterém řádku a při jakých hodnotách proměnných se vyskytla chyba.

Pro PHP se používá například debugger Xdebug, PHPStorm je jedním z nejoblíbenějších vývojových prostředí. Dále se podíváme, jak nakonfigurovat Xdebug v PhpStormu pro ladění na lokálním počítači a v Dockeru.

Konfigurace XDEBUG v PHPStormu

Probereme si, jak probíhá ladění na lokálním serveru.

Podívejme se na celý proces na příkladu Ubuntu a interpretu PHP nakonfigurovaného s Apache. U jiných konfigurací se cesty k souborům mohou lišit, ale podstata je stejná. Ladicí program Xdebug umožňuje pozastavit provádění kódu, zobrazit zásobník volání a obsah proměnných. Jeho jedinou nevýhodou je, že nemá žádné pohodlné ovládací rozhraní. Ke správě ladění se obvykle používají IDE. IDE však nemůže debuggeru říci, aby zahájil ladění, protože je zodpovědné pouze za kód. K tomuto účelu budete potřebovat rozšíření prohlížeče Debug Helper, s jehož pomocí můžete režim ladění zapnout.

Nejprve je třeba nainstalovat Xdebug. Za tímto účelem spusťte následující příkaz:

$ sudo apt install xdebug

Po dokončení instalace Xdebug byste měli program nakonfigurovat tak, aby se při spuštění relace ladění pokusil připojit k našemu IDE a ovládal ladění. Za tímto účelem přidejte do souboru /etc/php/7.4/apache2/conf.d/20-xdebug.ini ve verzi Xdebug 2 tyto řádky:

$ 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

Pro novější verzi je nejlepší použít jiný formát:

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

Podívejme se na nastavení blíže. První parametr xdebug.mode - režim ladění, možné volby jsou:

• develop - umožňuje vypisování dodatečných informací, nahrazuje var_dump;

• debug - režim provádění kódu po řádcích, je to režim, který v tomto případě potřebujeme;

• profile - profilování;

• trace -sledování provádění programu.

Při uvedení v čárkách je povoleno několik režimů současně. Druhý řádek xdebug.start_with_request definuje, jak bude debugger spuštěn pro režimy debug, trace a podobné:

• Ano - vždy, při spouštění php skriptů;
• ne - spustí se pouze z kódu používajícího speciální funkce;
• trigger - na vyžádání, pomocí speciální proměnné v $_ENV, $_POST, $COOKIE nebo jiném poli. Tato volba se v tomto případě hodí nejlépe, aby se debugger nespouštěl, když to není nutné.

Třetí možnost xdebug.discover_client_host je nastavena na true, v takovém případě se xdebug pokusí připojit k hostiteli předanému v hlavičce HTTP_X_FORWARDED_FOR. Vzhledem k tomu, že hostitel je zadán v dalším řádku, není tato funkce v tomto případě potřeba. Dále je hostitelem klienta, ke kterému se má připojit pro kontrolu ladění, 127.0.0.1 a port 9000. To je výchozí port, který se v současné době používá v systému PhpStorm. Po uložení nastavení je třeba restartovat Apache pomocí speciálního příkazu:

$ sudo systemctl restart apache2

Dále byste měli nakonfigurovat PhpStorm. Spusťte program a otevřete nabídku Spustit -> Upravit konfigurace. Zobrazí se okno, ve kterém je třeba nakonfigurovat ladicí program.

Klepněte na tlačítko + a v otevřeném seznamu vyberte možnost PHP Remote Debugger:

V nastavení nic neměňte, pouze zadejte název této metody ladění. Pokud nezadáte server, z něhož budou očekávána připojení, budou přijata všechna připojení.

Pokud chcete změnit port, ke kterému se bude Xdebug připojovat, otevřete Soubor -> Nastavení -> PHP -> Ladění -> DBGp Proxy. Zde můžete zadat požadovaný port.

Můžeme říci, že nyní je IDE připraveno. Nyní klikněte na chybu na horním panelu nástrojů. Program začne čekat, až se debugger připojí, a my do kódu vložíme několik bodů přerušení pouhým kliknutím před řádek s kódem:

Nyní zbývá pouze nakonfigurovat prohlížeč.Pro Chrome si můžete stáhnout speciální rozšíření. Nainstalujte jej a otevřete stránku, kterou chcete ladit. Klikněte na ikonu rozšíření a vyberte možnost Ladit. Ikona rozšíření zezelená:

Obnovte stránku a vraťte se do aplikace PHPStorm. Pokud bylo vše provedeno správně, spustí se tam relace ladění. Při prvním spuštění vás program může požádat o nastavení místních cest k souborům tak, aby odpovídaly vzdáleným cestám k souborům. Pro místní server zde nemusíte nic konfigurovat, stačí kliknout na tlačítko Přijmout:

Poté ladicí program zastaví provádění ve zvoleném bodě přerušení a v programu se objeví ladicí rozhraní:

Nyní si ukážeme, jak nakonfigurovat Xdebug PhpStorm a Docker.

Ladění PHP v DOCKERu

Docker může být poněkud záludný. Protože se ladicí program musí připojit k samotnému IDE, je třeba předat hostitele kontejneru. V systému Windows to lze provést pomocí adresy host.docker.internal. V Linuxu se to však ve výchozím nastavení neděje. Chcete-li takovou adresu přidat, musíte do souboru docker-compose přidat následující řádky:

extra_hosts:

host.docker.internal: host-gateway

Používáme následující adresářovou strukturu:

Minimální požadovaný soubor docker-compose.yaml bude vypadat takto:

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

Jednoduše deklarujeme dva kontejnery, nginx a php-fpm. V prvním z nich neprovádíme žádné změny, takže stačí vzít oficiální obraz, připojit zdrojovou složku, konfigurační soubor a přesměrovat port. Ve druhém kontejneru je nutné nainstalovat a nakonfigurovat Xdebug, takže bude muset být sestaven na základě oficiálního kontejneru php. U stejného kontejneru je nutné zadat direktivu extra_hosts, bez ní nebude nic fungovat. Konfigurace Nginxu je také zcela standardní:

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;
  }
}

Takto se nastavuje zpracování PHP skriptů v kontejneru php-fpm a přesměrování neexistujících URL na index.php, což je u mnoha frameworků a CMS zcela standardní. V souboru Dockerfile kontejneru php-fpm to vypadá takto:

Nainstalujte xdebug pomocí pecl a poté zkopírujte jeho konfigurační soubor do kontejneru. Soubor:

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

V kontejneru je nainstalován Xdebug 3 pro PHP 8, protože stará verze již s touto verzí jazyka nefunguje, a proto je použita nová konfigurační syntaxe. No host, host.docker.internal, který býval předepsán v souboru docker-compose.yaml. Konfigurace dockeru xdebug PHPStorm je nyní dokončena. Dále můžete projekt spustit:

docker-compose up --build

Nyní můžete stejně jako v předchozí možnosti povolit režim ladění v prohlížeči, obnovit stránku a ladicí program se úspěšně připojí k IDE, přestože běží v Dockeru