Konfigurácia Xdebug v aplikácii PHPStorm

Ladenie je jedným z najdôležitejších procesov v programovaní. Pomocou ladiaceho programu môžete vidieť, čo sa v programe deje, aké funkcie sa vykonávajú, čo je uložené v premenných, ako aj vykonať všetko krok za krokom a presne pochopiť, na ktorom riadku a pri ktorých hodnotách premenných sa vyskytla chyba.

Pre PHP sa používa napríklad debugger Xdebug, PHPStorm je jedno z najpopulárnejších vývojových prostredí. Ďalej si ukážeme, ako nakonfigurovať Xdebug v PhpStorm na ladenie na lokálnom počítači a v Dockeri.

Konfigurácia XDEBUG v PHPSTORM

Poďme si povedať, ako sa ladenie vykonáva na lokálnom serveri.

Pozrime sa na celý proces na príklade Ubuntu a interpretu PHP nakonfigurovaného s Apache. V prípade iných konfigurácií môžu byť cesty k súborom odlišné, ale podstata je rovnaká. Debugger Xdebug umožňuje pozastaviť vykonávanie kódu, zobraziť zásobník volaní a obsah premenných. Jeho jedinou nevýhodou je, že nemá pohodlné ovládacie rozhranie. Na riadenie ladenia sa zvyčajne používajú vývojové prostredia IDE. IDE však nemôže debuggeru prikázať, aby spustil ladenie, pretože je zodpovedný len za kód. Na tento účel budete potrebovať rozšírenie prehliadača Debug Helper, pomocou ktorého môžete zapnúť režim ladenia.

Najprv si musíte nainštalovať Xdebug. Ak to chcete urobiť, vykonajte nasledujúci príkaz:

$ sudo apt install xdebug

Po dokončení procesu inštalácie Xdebug by ste mali program nakonfigurovať tak, aby sa pri spustení relácie ladenia pokúsil pripojiť k nášmu IDE a riadiť ladenie. Na tento účel pridajte tieto riadky do súboru /etc/php/7.4/apache2/conf.d/20-xdebug.ini vo verzii 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

V prípade novšej verzie je najlepšie použiť iný 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

Pozrime sa bližšie na nastavenia. Prvý parameter xdebug.mode - režim ladenia, možné voľby sú:

• develop - umožňuje vypisovanie dodatočných informácií, prekrýva var_dump;

• debug - režim vykonávania kódu po riadkoch, je to režim, ktorý v tomto prípade potrebujeme;

• profile - profilovanie;

• trace -sledovanie vykonávania programu.

Viacero režimov je zapnutých súčasne, ak sú uvedené v čiarkach. Druhý riadok xdebug.start_with_request definuje spôsob spustenia ladiaceho programu pre režimy debug, trace a podobne:

• áno - vždy, pri spúšťaní php skriptov;
• nie - spustí sa len z kódu, ktorý používa špeciálne funkcie;
• trigger - na požiadanie, pomocou špeciálnej premennej v $_ENV, $_POST, $COOKIE alebo inom poli. Táto možnosť sa v tomto prípade hodí najlepšie, aby sa ladiaci program nespúšťal, keď to nie je potrebné.

Tretia možnosť xdebug.discover_client_host je nastavená na true, v takom prípade sa xdebug pokúsi pripojiť k hostiteľovi odovzdanému v hlavičke HTTP_X_FORWARDED_FOR. Keďže hostiteľ je uvedený v nasledujúcom riadku, táto funkcia nie je v tomto prípade potrebná. Ďalej je hostiteľom klienta, ku ktorému sa má pripojiť na účely kontroly ladenia, 127.0.0.1 a port 9000. Toto je predvolený port, ktorý sa v súčasnosti používa v programe PhpStorm. Po uložení nastavení je potrebné reštartovať Apache pomocou špeciálneho príkazu:

$ sudo systemctl restart apache2

Ďalej by ste mali nakonfigurovať PhpStorm. Spustite program a potom otvorte ponuku Spustiť -> Upraviť konfigurácie. Zobrazí sa okno, v ktorom je potrebné nakonfigurovať ladiaci program.

Kliknite na tlačidlo + a z otvoreného zoznamu vyberte položku PHP Remote Debugger:

V nastaveniach nič nemeňte, len zadajte názov tejto metódy ladenia. Ak nezadáte server, z ktorého sa budú očakávať spojenia, budú prijaté všetky spojenia.

Ak chcete zmeniť port, na ktorý sa bude Xdebug pripájať, otvorte Súbor -> Nastavenia -> PHP -> Ladenie -> DBGp Proxy. Tu môžete zadať požadovaný port.

Môžeme povedať, že teraz je IDE pripravené. Teraz kliknite na chybu na hornom paneli nástrojov. Program začne čakať, kým sa debugger pripojí, a my vložíme do kódu niekoľko bodov prerušenia jednoduchým kliknutím pred riadok s kódom:

Teraz už zostáva len nakonfigurovať prehliadač.Pre prehliadač Chrome si môžete stiahnuť špeciálne rozšírenie. Nainštalujte ho a otvorte stránku, ktorú chcete ladiť. Kliknite na ikonu rozšírenia a vyberte možnosť Debug. Ikona rozšírenia sa zmení na zelenú:

Obnovte stránku a vráťte sa do aplikácie PHPStorm. Ak bolo všetko vykonané správne, spustí sa tam relácia ladenia. Pri prvom spustení vás program môže požiadať o konfiguráciu lokálnych ciest k súborom tak, aby zodpovedali vzdialeným cestám k súborom. Pre miestny server tu nemusíte nič konfigurovať, stačí kliknúť na tlačidlo Prijať:

Potom ladiaci program zastaví vykonávanie na vybranom bode prerušenia a v programe sa objaví ladiace rozhranie:

Teraz pochopíme, ako nakonfigurovať Xdebug PhpStorm a Docker.

Ladenie PHP v DOCKER

Docker môže byť trochu zložitý. Keďže ladiaci program sa musí pripojiť k samotnému vývojovému prostrediu IDE, je potrebné presmerovať hostiteľa na kontajner. V systéme Windows to možno urobiť pomocou adresy host.docker.internal. V Linuxe sa to však štandardne nedeje. Ak chcete takúto adresu pridať, musíte do programu docker-compose pridať nasledujúce riadky:

extra_hosts:

host.docker.internal: host-gateway

Používame nasledujúcu adresárovú štruktúru:

Minimálne požadovaný súbor docker-compose.yaml bude vyzerať 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

Jednoducho deklarujeme dva kontajnery, nginx a php-fpm. V prvom z nich nerobíme žiadne zmeny, takže nám stačí vziať oficiálny obraz, pripojiť zdrojový priečinok, konfiguračný súbor a presmerovať port. V druhom kontajneri je potrebné nainštalovať a nakonfigurovať Xdebug, takže ho budeme musieť zostaviť na základe oficiálneho kontajnera php. Pre ten istý kontajner je potrebné zadať direktívu extra_hosts, bez nej nebude nič fungovať. Konfigurácia Nginx je tiež úplne štandardná:

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 sa konfiguruje spracovanie skriptov PHP v kontajneri php-fpm a presmerovanie neexistujúcich adries URL na index.php, čo je úplne štandardné pre mnohé frameworky a CMS. V súbore Dockerfile kontajnera php-fpm to vyzerá takto:

Nainštalujte xdebug pomocou pecl a potom skopírujte jeho konfiguračný súbor do kontajnera. Súbor:

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 pre PHP 8 je nainštalovaný v kontajneri, pretože stará verzia už s touto verziou jazyka nefunguje, preto sa používa nová konfiguračná syntax. No hostiteľ, host.docker.internal, ktorý býval predpísaný v docker-compose.yaml. Konfigurácia dockera xdebug PHPStorm je teraz kompletná. Ďalej môžete spustiť projekt:

docker-compose up --build

Teraz, rovnako ako v predchádzajúcej možnosti, môžete v prehliadači zapnúť režim ladenia, obnoviť stránku a ladiaci program sa úspešne pripojí k IDE, napriek tomu, že beží v Docker