Jak na funkční xdebug v dockeru

Neumím si představit práci bez debuggeru. Nikdy jsem rozchozením xdebugu neměl problém, až do té doby, než jsem začal používat Docker. Nějakou dobu jsem používal pro výpis dump() respektive var_dump(), ale bylo to velice otravné. Nakonec jsem věnoval den zkoumání jak xdebug zprovoznit v Dockeru.

update 06.10.2021 – konfigurace pro xdebug 3.0

Nastavení sítě

Začneme nastavením sítě. Aby xdebug věděl, kam má posílat packety, musíme mu v dockeru nastavit cílovou adresu. Klidně můžeme uvést aktuální IP adresu počítače, má to ale jednu velkou nevýhodu. Pokud používáte DHCP, případně občas pracujete na jiné síti, IP adresu by bylo potřeba v konfiguraci stále měnit. Lepší je přidat síťové kartě extra IP adresu, která se nebude měnit. V konzoli zadejte

sudo ip a add 10.254.254.254/24 dev lo

Jako zařízení jsem uvedl lo – loopback. Je na každém počítači, nemusíte přemýšlet nad označením síťovky, kterou máte v systému, navíc NetworkManager se nebude snažit nastavení přepisovat.

Příprava systemd service

Nastavení zadáním do konzole nepřežije restart, lepší je vytvořit systemd service. Dříve stačilo příkaz zadat do /etc/rc.local, po nástupu systemd bylo toto řešení označeno jako zastaralé. Naštěstí vytvoření service není nic složitého.

Jako první si vytvoříme script, který nastavení provede.
Do /usr/local/bin/xdebug-ip.bash vložíme:

#!/bin/bash
ip a add 10.254.254.254 dev lo

nastavíme script spustitelný pomocí

chmod +x /usr/local/bin/xdebug-ip.bash

Do /etc/systemd/system/xdebug-ip.service vložte:

[Unit]
Description=Spark service

[Service]
ExecStart=/usr/local/bin/xdebug-ip.bash

[Install]
WantedBy=multi-user.target

Systemd unit musíme zapnout a pak nastartovat:

sudo systemctl enable xdebug-ip
sudo systemctl start xdebug-ip

Můžeme ověřit, jestli loopback dostal i druhou adresu pomocí příkazu ip a:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet 10.254.254.254/32 scope global lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host 

Konfigurace dockeru

V Dockerfile musíme xdebug nainstalovat. Používám pro to tento script:

RUN touch /usr/local/etc/php/php.ini
RUN pear config-set php_ini /usr/local/etc/php/php.ini
RUN pecl config-set php_ini /usr/local/etc/php/php.ini
RUN pecl install xdebug-2.6.0
RUN docker-php-ext-enable xdebug
RUN echo 'xdebug.remote_enable=1' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.remote_autostart=1' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.idekey=PHPSTORM' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.default_enable=1' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.remote_connect_back=0' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.profiler_enabled=0' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.remote_host=10.254.254.254' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.remote_port=9000' >> /usr/local/etc/php/php.ini

Nastavení pro xdebug 3.0:

RUN export XDEBUG_SESSION=PHPSTORM
RUN touch /usr/local/etc/php/php.ini
RUN pear config-set php_ini /usr/local/etc/php/php.ini
RUN pecl config-set php_ini /usr/local/etc/php/php.ini
RUN pecl install xdebug
RUN docker-php-ext-enable xdebug
RUN echo 'xdebug.mode=debug' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.idekey=PHPSTORM' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.discover_client_host=false' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.client_host=10.254.254.254' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.client_port=9000' >> /usr/local/etc/php/php.ini
RUN echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/php.ini

Nainstaluje se rozšíření a nastaví se. Pokud použijete jinou IP adresu než 10.254.254.254, musíte ji změnit i zde v nastavení xdebugu.

Do docker-compose.yml:

    expose:
      - 9000

Nastavení na straně dockeru a sítě je hotovo. Existující kontejner je třeba znovu sestavit aby se nainstalovat xdebug a provedlo jeho nastavení. To lze provést příkazem:

docker-compose up --build

Nastavení PHPStorm

V menu File -> Settings -> Languages & Frameworks -> Debug -> DBGp Proxy

Dále pak v File -> Settings -> Languages & Frameworks -> Servers přidat server a nastavit podle obrázku (pozor na port, musí být také 9000):

Důležité je mít zvoleno Use path mappings a správně nastavenu cestu. V druhém sloupci na obrázku je /var/www/html umístění zdrojáků v dockeru.

V Run -> Edit connections červeným tlačítkem + přidat PHP Remote Debug, nastavit podle obrázku:

V Run je potřeba vybrat Start listening for PHP debug connections. Menu Run -> Break at first line in PHP scripts musí být odškrknuto. Jinak by se provádění zastavilo vždy na prvním řádku a ne až na místě breakpointu.

Teď stačí nastavit breakpoint, udělat refresh v prohlížeči, přijmout v PHP Stormu connection od xdebugu:

a tradá:

Bez funkčního xdebugu si neumím ladění představit. Jsem moc rád, že se mi vše povedlo nastavit a mohu pohodlně ladit i aplikaci spuštěnou v dockeru.

Když to nefunguje

• zkontrolujte, jestli spojení na xdebug nezahazuje firewall

Další typy budu doplňovat podle ohlasů.