Configurazione di Xdebug in PHPStorm

Il debug è uno dei processi più importanti della programmazione. Con l'aiuto di un debugger è possibile vedere cosa succede nel programma, quali funzioni vengono eseguite, cosa viene memorizzato nelle variabili, nonché eseguire tutto passo dopo passo e capire esattamente su quale riga e a quali valori delle variabili si verifica un errore.

Per esempio, il debugger Xdebug è utilizzato per PHP, PHPStorm è uno degli ambienti di sviluppo più popolari. Vediamo ora come configurare Xdebug in PhpStorm per il debug sul computer locale e in Docker.

Configurazione di XDEBUG in PHPSTORM

Parliamo di come viene eseguito il debug sul server locale.

Vediamo l'intero processo utilizzando come esempio Ubuntu e l'interprete PHP configurato con Apache. Per altre configurazioni i percorsi dei file possono essere diversi, ma il punto è lo stesso. Il debugger Xdebug consente di mettere in pausa l'esecuzione del codice, di visualizzare lo stack delle chiamate e il contenuto delle variabili. Il suo unico svantaggio è la mancanza di una comoda interfaccia di controllo. Per gestire il debug, di solito si utilizzano gli IDE. Ma l'IDE non può dire al debugger di avviare il debug perché è responsabile solo del codice. A questo scopo è necessaria l'estensione del browser Debug Helper, con l'aiuto della quale è possibile attivare la modalità di debug.

Per prima cosa è necessario installare Xdebug. Per farlo, eseguire:

$ sudo apt install xdebug

Una volta completato il processo di installazione di Xdebug, è necessario configurare il programma in modo che quando si avvia una sessione di debug cerchi di connettersi al nostro IDE per controllare il debug. A tal fine, aggiungere queste righe al file /etc/php/7.4/apache2/conf.d/20-xdebug.ini nella versione 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

Per una versione più recente, è meglio usare un formato diverso:

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

Diamo un'occhiata più da vicino alle impostazioni. Il primo parametro xdebug.mode - modalità di debug, le opzioni possibili sono:

• develop - abilita l'output di informazioni aggiuntive, sovrascrive var_dump;

• debug - modalità di esecuzione del codice riga per riga, è la modalità di cui abbiamo bisogno in questo caso;

• profile - profilazione;

• trace -tracciamento dell'esecuzione del programma.

Diverse modalità sono abilitate contemporaneamente quando sono elencate tra virgole. La seconda riga xdebug.start_with_request definisce come verrà avviato il debugger per le modalità debug, trace e simili:

• yes - sempre, quando si eseguono script php;
• no - si avvia solo dal codice usando funzioni speciali;
• trigger - su richiesta, usando una variabile speciale in $_ENV, $_POST, $COOKIE o altri array. Questa opzione è la più adatta in questo caso, in modo che il debugger non venga eseguito quando non è necessario.

La terza opzione xdebug.discover_client_host è impostata su true, nel qual caso xdebug tenta di connettersi all'host passato nell'intestazione HTTP_X_FORWARDED_FOR. Poiché l'host è specificato nella riga successiva, questa funzione non è necessaria in questo caso. Successivamente, l'host client a cui connettersi per il controllo del debug è 127.0.0.1 e la porta 9000. Questa è la porta predefinita utilizzata in PhpStorm al momento. Dopo aver salvato le impostazioni, è necessario riavviare Apache con un comando speciale:

$ sudo systemctl restart apache2

Successivamente, si deve configurare PhpStorm. Avviare il programma, quindi aprire il menu Esegui -> Modifica configurazioni. Verrà visualizzata una finestra in cui è necessario configurare il debugger.

Fare clic sul pulsante + e selezionare PHP Remote Debugger dall'elenco che si apre:

Non modificare nulla nelle impostazioni, basta specificare il nome di questo metodo di debug. Se non si specifica il server da cui si attendono le connessioni, tutte le connessioni saranno accettate.

Se si desidera modificare la porta alla quale Xdebug si connetterà, aprire File -> Impostazioni -> PHP -> Debug -> DBGp Proxy. Qui è possibile specificare la porta desiderata.

Possiamo dire che ora l'IDE è pronto. Ora cliccate sul bug nella barra degli strumenti superiore. Il programma inizierà ad aspettare che il debugger si connetta e noi metteremo alcuni punti di interruzione nel codice semplicemente facendo clic davanti alla riga con il codice:

Ora non resta che configurare il browser.Per Chrome, è possibile scaricare un'estensione speciale. Installatela e aprite la pagina di cui volete eseguire il debug. Fare clic sull'icona dell'estensione e selezionare Debug. L'icona dell'estensione diventerà verde:

Aggiornare la pagina e tornare a PHPStorm. Se tutto è stato fatto correttamente, si avvierà una sessione di debug. Al primo avvio, il programma potrebbe chiedere di configurare i percorsi dei file locali in modo che corrispondano ai percorsi dei file remoti. Per il server locale non è necessario configurare nulla, basta fare clic su Accetta:

Dopodiché il debugger interromperà l'esecuzione al punto di interruzione selezionato e l'interfaccia di debug apparirà nel programma:

Ora vediamo come configurare Xdebug PhpStorm e Docker.

Debug di PHP in Docker

Docker può essere un po' complicato. Poiché il debugger deve connettersi all'IDE stesso, è necessario inoltrare l'host al container. Su Windows, questo può essere fatto usando l'indirizzo host.docker.internal. Ma in Linux, questo non avviene per impostazione predefinita. Per aggiungere tale indirizzo è necessario aggiungere le seguenti righe a docker-compose:

extra_hosts:

host.docker.internal: host-gateway

Utilizziamo la seguente struttura di directory:

Il file docker-compose.yaml minimo richiesto avrà questo aspetto:

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

Dichiariamo semplicemente due contenitori, nginx e php-fpm. Non apportiamo alcuna modifica al primo, quindi possiamo semplicemente prendere l'immagine ufficiale, montare la cartella sorgente, il file di configurazione e il port forward. Nel secondo contenitore è necessario installare e configurare Xdebug, quindi dovrà essere costruito sulla base del contenitore php ufficiale. Per lo stesso contenitore è necessario specificare la direttiva extra_hosts, senza la quale non funzionerà nulla. Anche la configurazione di Nginx è abbastanza standard:

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

È così che si configura l'elaborazione degli script PHP nel contenitore php-fpm e il reindirizzamento di URL inesistenti a index.php, che è abbastanza standard per molti framework e CMS. Nel file Docker del contenitore php-fpm, si presenta così:

Installare xdebug usando pecl e poi copiare il suo file di configurazione nel contenitore. File:

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 per PHP 8 è installato nel contenitore, perché la vecchia versione non funziona più con questa versione del linguaggio, quindi viene utilizzata la nuova sintassi di configurazione. Bene host, host.docker.internal, che prima era prescritto in docker-compose.yaml. La configurazione di xdebug PHPStorm docker è ora completa. Quindi, si può eseguire il progetto:

docker-compose up --build

Ora, come nell'opzione precedente, si può abilitare la modalità di debug nel browser, aggiornare la pagina e il debugger si connetterà con successo all'IDE, nonostante il fatto che sia in esecuzione in Docker.