Xdebugin määrittäminen PHPStormissa

Virheenkorjaus on yksi ohjelmoinnin tärkeimmistä prosesseista. Virheenkorjaajan avulla voit nähdä, mitä ohjelmassa tapahtuu, mitä funktioita suoritetaan, mitä muuttujiin tallennetaan ja mitä muuttujiin tallennetaan, sekä suorittaa kaiken vaiheittain ja ymmärtää tarkalleen, millä rivillä ja millä muuttujien arvoilla virhe tapahtuu.

Esimerkiksi Xdebug-virheenkorjausohjelmaa käytetään PHP:ssä, PHPStorm on yksi suosituimmista kehitysympäristöistä. Seuraavaksi katsotaan, miten Xdebug konfiguroidaan PhpStormissa debuggausta varten paikallisella tietokoneella ja Dockerissa.

XDEBUGin määrittäminen PHPSTORMissa

Puhutaan siitä, miten virheenkorjaus tehdään paikallisella palvelimella.

Tarkastellaan koko prosessia käyttäen esimerkkinä Ubuntua ja Apachen kanssa konfiguroitua PHP-tulkkia. Muissa kokoonpanoissa tiedostopolut voivat olla erilaiset, mutta pointti on sama. Xdebug-virheenkorjausohjelman avulla voit pysäyttää koodin suorituksen, tarkastella kutsupinoa ja muuttujien sisältöä. Sen ainoa haittapuoli on se, että siinä ei ole kätevää ohjausliittymää. Debuggauksen hallintaan käytetään yleensä IDE-ohjelmia. IDE ei kuitenkaan voi käskeä debuggeria aloittamaan debuggausta, koska se on vastuussa vain koodista. Tätä varten tarvitset Debug Helper -selainlaajennuksen, jonka avulla voit ottaa käyttöön debuggaustilan.

Ensin sinun on asennettava Xdebug. Suorita tätä varten:

$ sudo apt install xdebug

Kun Xdebugin asennusprosessi on valmis, sinun on määritettävä ohjelma niin, että kun aloitat debuggausistunnon, se yrittää muodostaa yhteyden IDE-ohjelmaamme debuggauksen ohjaamiseksi. Tätä varten lisää nämä rivit Xdebug 2 -version tiedostoon /etc/php/7.4/apache2/conf.d/20-xdebug.ini:

$ 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

Uudemmassa versiossa on parasta käyttää eri muotoa:

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

Katsotaanpa asetuksia tarkemmin. Ensimmäinen parametri xdebug.mode - virheenkorjaustila, mahdolliset vaihtoehdot ovat:

• ohittaa var_dumpin:develop - mahdollistaa lisätietojen tulostamisen, ohittaa var_dumpin;

• debug - koodin rivikohtaisen suorituksen tila, se on tässä tapauksessa tarvitsemamme tila;

• profile - profilointi;

• trace - ohjelman suorituksenjäljittäminen.

Useat tilat ovat käytössä samanaikaisesti, kun ne on lueteltu pilkkujen välissä. Toinen rivi xdebug.start_with_request määrittelee, miten debuggeri käynnistetään debug-, trace- ja vastaavissa tiloissa:

• yes - aina, kun suoritetaan php-skriptejä;
• no - käynnistyy vain koodista, jossa käytetään erikoisfunktioita;
• trigger - pyydettäessä, käyttämällä erityistä muuttujaa $_ENV, $_POST, $COOKIE tai muussa joukossa. Tämä vaihtoehto sopii tässä tapauksessa parhaiten, jotta debuggeri ei käynnisty silloin, kun se ei ole tarpeen.

Kolmas xdebug.discover_client_host on true, jolloin xdebug yrittää muodostaa yhteyden HTTP_X_FORWARDED_FOR-otsakkeessa välitettyyn isäntään. Koska isäntä määritetään seuraavalla rivillä, tätä ominaisuutta ei tässä tapauksessa tarvita. Seuraavaksi asiakashost, johon otetaan yhteys debuggausvalvontaa varten, on 127.0.0.1 ja portti 9000. Tämä on PhpStormissa tällä hetkellä käytetty oletusportti. Kun olet tallentanut asetukset, sinun on käynnistettävä Apache uudelleen erityisellä komennolla:

$ sudo systemctl restart apache2

Seuraavaksi sinun tulee konfiguroida PhpStorm. Käynnistä ohjelma ja avaa sitten Run -> Edit Configurations -valikko. Näet ikkunan, jossa sinun täytyy määrittää debuggeri.

Napsauta +-painiketta ja valitse avautuvasta luettelosta PHP Remote Debugger:

Älä muuta asetuksissa mitään, määritä vain tämän debuggausmenetelmän nimi. Jos et määritä palvelinta, jolta yhteyksiä odotetaan, kaikki yhteydet hyväksytään.

Jos haluat muuttaa porttia, johon Xdebug muodostaa yhteyden, avaa File -> Settings -> PHP -> Debug -> DBGp Proxy. Tässä voit määrittää haluamasi portin.

Voimme sanoa, että nyt IDE on valmis. Napsauta nyt vikakohtaa ylätyökalurivillä. Ohjelma alkaa odottaa debuggerin yhteyden muodostumista ja laitamme koodiin joitakin breakpointteja klikkaamalla koodia sisältävän rivin eteen:

Nyt jäljellä on enää selaimen konfigurointi.Chromea varten voit ladata erityisen laajennuksen. Asenna se ja avaa sivu, jonka haluat debugata. Napsauta laajennuksen kuvaketta ja valitse Debug. Laajennuksen kuvake muuttuu vihreäksi:

Päivitä sivu ja palaa PHPStormiin. Jos kaikki tehtiin oikein, debuggausistunto alkaa siellä. Ensimmäisellä ajokerralla ohjelma saattaa pyytää sinua määrittämään paikalliset tiedostopolut vastaamaan etätiedostopolkuja. Paikallista palvelinta varten sinun ei tarvitse määrittää tässä kohtaa mitään, klikkaa vain Hyväksy:

Tämän jälkeen debuggeri pysäyttää suorituksen valittuun katkaisupisteeseen ja ohjelmaan ilmestyy debuggauskäyttöliittymä:

Ymmärretään nyt, miten Xdebug PhpStorm ja Docker määritetään.

PHP:n virheenkorjaus DOCKERissa

Docker voi olla hieman hankala. Koska debuggerin on otettava yhteys itse IDE:hen, sinun on välitettävä isäntä konttiin. Windowsissa tämä voidaan tehdä käyttämällä osoitetta host.docker.internal. Linuxissa tämä ei kuitenkaan tapahdu oletusarvoisesti. Tällaisen osoitteen lisäämiseksi sinun täytyy lisätä seuraavat rivit docker-composeen:

extra_hosts:

host.docker.internal: host-gateway

Käytämme seuraavaa hakemistorakennetta:

Vähintään vaadittu docker-compose.yaml näyttää tältä:

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

Ilmoitamme yksinkertaisesti kaksi konttia, nginxin ja php-fpm:n. Emme tee mitään muutoksia ensimmäiseen, joten voimme vain ottaa virallisen kuvan, mountata lähdekansion, konfigurointitiedoston ja portin eteenpäin. Toiseen konttiin on tarpeen asentaa ja konfiguroida Xdebug, joten se on rakennettava virallisen php-kontin pohjalta. Samaan konttiin on määriteltävä extra_hosts-direktiivi, ilman sitä mikään ei toimi. Nginxin konfigurointi on myös melko vakio:

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

Näin määritetään PHP-skriptien käsittely php-fpm-säiliössä ja ohjataan olemattomat URL-osoitteet index.php:hen, mikä on melko vakio monissa kehyksissä ja CMS-järjestelmissä. php-fpm-säiliön Docker-tiedostossa se näyttää tältä:

Asenna xdebug käyttäen pecl:ää ja kopioi sen konfigurointitiedosto konttiin. Tiedosto:

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 for PHP 8 asennetaan konttiin, koska vanha versio ei enää toimi tämän kieliversion kanssa, joten käytetään uutta konfiguraatiosyntaksia. No host, host.docker.internal, joka aiemmin oli määrätty docker-compose.yaml:ssä. xdebug PHPStorm-dockerin konfigurointi on nyt valmis. Seuraavaksi voit ajaa projektin:

docker-compose up --build

Nyt, kuten edellisessä vaihtoehdossa, voit ottaa debug-tilan käyttöön selaimessa, päivittää sivun ja debuggeri muodostaa onnistuneesti yhteyden IDE:hen huolimatta siitä, että se on käynnissä Dockerissa