Xdebug configureren in PHPStorm

Debuggen is een van de belangrijkste processen bij het programmeren. Met behulp van een debugger kun je zien wat er in het programma gebeurt, welke functies worden uitgevoerd, wat er in variabelen is opgeslagen, alles stap voor stap uitvoeren en precies begrijpen op welke regel en bij welke waarden van variabelen een fout optreedt.

Xdebug debugger wordt bijvoorbeeld gebruikt voor PHP, PHPStorm is een van de populairste ontwikkelomgevingen. Laten we nu eens kijken hoe je Xdebug configureert in PhpStorm voor debuggen op een lokale computer en in Docker.

XDEBUG configureren in PHPSTORM

Laten we het hebben over hoe debuggen wordt gedaan op de lokale server.

Laten we het hele proces bekijken met Ubuntu en de PHP-interpreter geconfigureerd met Apache als voorbeeld. Voor andere configuraties kunnen de bestandspaden anders zijn, maar het punt is hetzelfde. Met de Xdebug debugger kun je de uitvoering van code pauzeren, de aanroepstapel en de inhoud van variabelen bekijken. Het enige nadeel is dat er geen handige besturingsinterface is. IDE's worden meestal gebruikt om debuggen te beheren. Maar IDE's kunnen de debugger niet vertellen om te beginnen met debuggen omdat het alleen verantwoordelijk is voor de code. Hiervoor heb je de Debug Helper browserextensie nodig, waarmee je de debugmodus kunt inschakelen.

Eerst moet je Xdebug installeren. Voer dit uit:

$ sudo apt install xdebug

Zodra het installatieproces van Xdebug is voltooid, moet je het programma zo configureren dat wanneer je een debugsessie start, het probeert verbinding te maken met onze IDE om het debuggen te regelen. Voeg hiervoor deze regels toe aan het bestand /etc/php/7.4/apache2/conf.d/20-xdebug.ini in de versie 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

Voor een nieuwere versie kun je het beste een ander formaat gebruiken:

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

Laten we de instellingen eens nader bekijken. De eerste parameter xdebug.mode - debugmodus, mogelijke opties zijn:

• develop - schakelt uitvoer van extra informatie in, overschrijft var_dump;

• debug - modus voor regel-voor-regel code-uitvoering, dit is de modus die we in dit geval nodig hebben;

• profile - profileren;

• trace - traceren van programma-uitvoering.

Verschillende modi worden tegelijkertijd ingeschakeld als ze tussen komma's staan. De tweede regel xdebug.start_with_request definieert hoe de debugger wordt gestart voor debug, trace en soortgelijke modi:

• yes - altijd, wanneer php-scripts worden uitgevoerd;
• nee - alleen starten vanuit code met behulp van speciale functies;
• trigger - op verzoek, met behulp van een speciale variabele in $_ENV, $_POST, $COOKIE of een andere array. Deze optie past in dit geval het beste, zodat de debugger niet draait wanneer dat niet nodig is.

De derde xdebug.discover_client_host is ingesteld op true, in welk geval xdebug probeert te verbinden met de host die is doorgegeven in de HTTP_X_FORWARDED_FOR header. Aangezien de host in de volgende regel wordt gespecificeerd, is deze functie in dit geval niet nodig. Vervolgens is de client host om verbinding mee te maken voor het debuggen 127.0.0.1 en poort 9000. Dit is de standaard poort die op dit moment in PhpStorm wordt gebruikt. Na het opslaan van de instellingen moet Apache opnieuw opgestart worden met een speciaal commando:

$ sudo systemctl restart apache2

Vervolgens moet je PhpStorm configureren. Start het programma en open vervolgens het menu Uitvoeren -> Configuraties bewerken. Er verschijnt een venster waarin je de debugger moet configureren.

Klik op de knop + en selecteer PHP Remote Debugger in de lijst die wordt geopend:

Verander niets aan de instellingen, geef alleen de naam van deze debugmethode op. Als je niet aangeeft van welke server verbindingen worden verwacht, worden alle verbindingen geaccepteerd.

Als je de poort wilt wijzigen waarmee Xdebug verbinding maakt, open dan Bestand -> Instellingen -> PHP -> Debug -> DBGp Proxy. Hier kun je de gewenste poort opgeven.

We kunnen zeggen dat de IDE nu klaar is. Klik nu op de bug op de bovenste werkbalk. Het programma begint te wachten tot de debugger verbinding maakt en we zetten een aantal breakpoints in de code door gewoon voor de regel met de code te klikken:

Nu rest alleen nog het configureren van de browser.Voor Chrome kun je een speciale extensie downloaden. Installeer deze en open de pagina die je wilt debuggen. Klik op het extensiepictogram en selecteer Debug. Het extensiepictogram wordt groen:

Ververs de pagina en ga terug naar PHPStorm. Als alles correct is uitgevoerd, wordt daar een debugsessie gestart. Tijdens de eerste run kan het programma je vragen om lokale bestandspaden te configureren zodat deze overeenkomen met bestandspaden op afstand. Voor de lokale server hoef je hier niets te configureren, klik gewoon op Accepteren:

Daarna stopt de debugger de uitvoering op het geselecteerde breekpunt en verschijnt de debuginterface in het programma:

Laten we nu begrijpen hoe je Xdebug PhpStorm en Docker configureert.

PHP debuggen in DOCKER

Docker kan een beetje lastig zijn. Omdat de debugger verbinding moet maken met de IDE zelf, moet je de host doorsturen naar de container. Op Windows kan dit met het adres host.docker.internal. Maar in Linux gebeurt dit niet standaard. Om zo'n adres toe te voegen moet je de volgende regels toevoegen aan docker-compose:

extra_hosts:

host.docker.internal: host-gateway

We gebruiken de volgende directorystructuur:

De minimaal vereiste docker-compose.yaml ziet er zo uit:

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

We declareren simpelweg twee containers, nginx en php-fpm. We brengen geen wijzigingen aan in de eerste, dus we kunnen gewoon de officiële image nemen, de bronmap mounten, het configuratiebestand en de poort doorsturen. In de tweede container is het nodig om Xdebug te installeren en te configureren, dus deze moet worden gebouwd op basis van de officiële php-container. Voor dezelfde container is het nodig om de extra_hosts richtlijn op te geven, zonder zal niets werken. De configuratie van Nginx is ook vrij standaard:

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

Zo configureer je de verwerking van PHP-scripts in de php-fpm-container en leid je niet-bestaande URL's om naar index.php, wat vrij standaard is voor veel frameworks en CMS. In de Dockerfile van de php-fpm container ziet het er als volgt uit:

Installeer xdebug met behulp van pecl, en kopieer vervolgens het config-bestand ervan naar de container. Bestand:

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 voor PHP 8 wordt geïnstalleerd in de container, omdat de oude versie niet meer werkt met deze versie van de taal, dus wordt de nieuwe configuratiesyntax gebruikt. Nou host, host.docker.internal, die vroeger werd voorgeschreven in docker-compose.yaml. De configuratie van xdebug PHPStorm docker is nu voltooid. Vervolgens kun je het project uitvoeren:

docker-compose up --build

Nu kun je, net als in de vorige optie, de debugmodus inschakelen in de browser, de pagina verversen en de debugger zal met succes verbinding maken met de IDE, ondanks het feit dat het draait in Docker