[risolto] Aiuto, Xdebug non funziona e PHP non si ferma ai breakpoint con Visual Studio Code o phpStorm: cosa devo fare?

Prima o poi capita a tutti: abbiamo già installato Xdebug, configurato PHP e il nostro IDE (Visual Studio Code, phpStorm ecc), ma non è cambiato nulla! Le pagine PHP vengono caricate come al solito, l'esecuzione delle pagine PHP non si ferma sui breakpoint e non riusciamo a svolgere l'esecuzione step-by-step. Ebbene: in questo articolo vedremo proprio come affrontare questo problema e cosa fare quando Xdebug non funziona e PHP non si ferma ai breakpoint con Visual Studio Code o phpStorm

Trattazione aggiornata e verificata ad agosto 2024

La guida è incentrata su PHP e Xdebug con Visual Studio Code o phpStorm in ambiente Windows o Linux (Ubuntu, in particolare), ma le soluzioni proposte so valide anche con qualsiasi altro IDE e qualsiasi sistema operativo.

Prima di iniziare, è però opportuno consultare le guide specifiche:

• Xdebug con Visual Studio Code: Come configurare Xdebug e Visual Studio Code
• Xdebug con phpStorm: Guida a phpStorm e Xdebug

Nel prosieguo, daremo per scontato che l'installazione e la configurazione sia già stata svolta.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 1: Verificare che Xdebug sia attivo

La primissima verifica da svolgere è che Xdebug sia installato correttamente. Allo scopo, creiamo un file di nome test.php nella cartella del nostro sito, e incolliamovi questa singola riga:

<?php phpinfo();

Ora visualizziamo questa pagina tramite il browser web, quindi cerchiamo il testo xdebug all'interno della pagina. Dovremo così trovare un'indicazione simile a with Xdebug v3.0.3, Copyright (c) 2002-2021, by Derick Rethans nel rettangolo grigio subito dopo alla prima tabella

In caso questo testo non appaia, significa che Xdebug non è stato caricato. Un motivo comune? Xdebug è stato installato, ma poi abbiamo dimenticato di riavviare PHP-FPM. Facciamolo ora:

• con Ubuntu: sudo service php8.0-fpm restart (sostituire con la versione di PHP in uso)
• con Windows: riavviare il server web

Se il problema persiste, rivolgete l'attenzione alla sommità della pagina, dove viene riportata l'indicazione PHP Version. È questa la versione per la quale avete installato e configurato Xdebug?

Se sembra tutto in ordine ma ancora Xdebug non viene caricato, ci sono due possibilità:

1. Xdebug non è stato installato correttamente
2. PHP non è stato configurato correttamente per caricare Xdebug

Per risolvere entrambi i problemi, raccomando di seguire la guida dedicata:

» Leggi: Xdebug con Ubuntu - Come installare e configurare PHP per il debugging locale o remoto

PHP/Xdebug non si ferma ai breakpoint, Soluzione 2: File di configurazione

Come ho già avuto modo di spiegare nelle altre guide, è Xdebug che si connette a Visual Studio Code, phpStorm ecc., e non viceversa. Questo significa che il PC sul quale è in esecuzione l'IDE deve accettare la connessione da Xdebug

Se l'IDE e l'interprete PHP con Xdebug sono sullo stesso PC (o, comunque, all'interno della stessa rete locale) siamo in uno scenario di debug locale ed è opportuno utilizzare la direttiva che fa sì che Xdebug tenti una connessione diretta. Confrontiamo quindi il file di configurazione di Xdebug con questo, e assicuriamoci che siano simili. Nello specifico, è di importanza critica che si legga xdebug.discover_client_host = true

Se però il PC con l'IDE e quello che esegue PHP sono realmente "remoti", ovvero sono separati da Internet, siamo nello scenario di debug remoto. In tal caso, dobbiamo utilizzare un file di configurazione differente (questo), che riporta xdebug.discover_client_host = false (oppure nel quale la direttiva in questione è totalmente assente, dato che vale false di default).

In ogni caso, assicuriamoci sempre che il valore riportato dal nostro file con phpinfo() sia effettivamente quello che ci aspettiamo

In caso contrario, significa che l'interprete PHP non sta leggendo il nostro file di configurazione: verifichiamo di averlo posizionato opportunamente.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 3: Tunnel SSH attivo

Questo punto si applica solo a phpStorm. Con Visual Studio Code, la direttiva "RemoteForward" indicata di seguito NON deve essere presente.

Se siamo in uno scenario di "debug remoto", ricordiamo che la connessione da Xdebug al nostro IDE passa per il tunnel SSH. Questo implica che detto tunnel debba essere debitamente configurato, così come descritto in questo approfondimento:

» Leggi: [guida] Come configurare la connessione SSH con tunnel, proxy e chiavi diverse

Nello specifico, vogliamo assicurarci che il "profilo" di connessione al server SSH includa una direttiva simile a questa:

RemoteForward 9003 localhost:9001

Così facendo, la porta locale 9001 del PC con Visual Studio Code diverrà contattabile dal server con PHP e Xdebug sulla sua porta 9003 (utilizzata di default da Xdebug). Di nuovo: fate riferimento alla guida dedicata a .ssh/config per le istruzioni passo passo alla creazione di questo "profilo".

L'altro aspetto importante è che questa connessione deve essere "viva e attiva" perché il debugger funzioni. Di conseguenza, dobbiamo stabilire la connessione SSH prima di iniziare il debug, ed assicurarci che sia attiva: se cade la linea per qualche istante, ad esempio, la connessione SSH potrebbe "morire" senza che sia immediatamente chiaro. Per verificarlo, battiamo Invio un paio di volte all'interno del terminale: se non vediamo il prompt di comando, significa che la connessione non è più disponibile.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 4: Verificare che la porta sia aperta

Una volta mi è capitato che la sessione di debug non funzionasse perché la porta che avrebbe dovuto essere usata dall'IDE per accettare la connessione da Xdebug era già occupata da un altro processo. È quindi importante controllare che l'IDE sia effettivamente "in ascolto" sulla porta giusta.

Allo scopo, iniziamo avviando la sessione di debug nell'IDE, dopodiché esaminiamo quali porte siano in uso:

• con Windows: usiamo CurrPorts
• con Linux: impartiamo sudo ss -lpt oppure sudo netstat -tuanp

Se tutto sta funzionando correttamente, noteremo il processo di Visual Studio Code, phpStorm ecc. in attesa sulla porta designata

In caso contrario, dobbiamo capire quale processo stia occupando la porta, e chiuderlo.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 5: Verificare che le porte coincidano

Sempre rimanendo in tema di porte: è importante verificare che la porta aperta dall'IDE e quella alla quale Xdebug tenta di connettersi sia effettivamente la stessa. In un contesto di debug locale, questo è davvero molto semplice.

Possiamo scoprire facilmente quale porta sia usata dall'IDE utilizzando gli strumenti indicati alla Soluzione precedente.

Per quanto riguarda Xdebug, invece:

1. riprendiamo il file test.php creato durante la precedente Soluzione 1
2. cerchiamo xdebug.client_port all'interno della pagina
3. prestiamo attenzione al valore della prima colonna (Local Value): indica il numero della porta alla quale Xdebug tenta di connettersi

Se le porte sono diverse, dobbiamo modificare una delle due configurazioni, a scelta. Potendo scegliere, è comunque forse più facile e veloce cambiare l'impostazione nel proprio IDE

Non dimentichiamo di riavviare la sessione di debug dopo averlo fatto. Se invece abbiamo modificato la porta lato-Xdebug, riavviamo PHP.

Le cose sono leggermente più complicate se stiamo svolgendo il "debug remoto" con phpStorm. In tal caso, abbiamo aperto un tunnel SSH che potrebbe congiungere due porte diverse. Per verificarlo, prestiamo nuovamente attenzione alla direttiva RemoteForward 9003 localhost:9001 precedentemente aggiunta al file .ssh/config. Tale indicazione fa sì che la porta 9003 remota venga connessa alla 9001 locale. Dobbiamo quindi verificare che l'IDE sia in ascolto sulla seconda (9001), mentre Xdebug tenti di connettersi alla prima (9003): il tunnel SSH provvederà a metterle in comunicazione.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 6: Mapping dei percorsi

Affinché il debugging possa funzionare, è necessario che l'IDE abbia a disposizione il file giusto da mostrare. Di più: l'IDE deve poter conoscere il percorso in cui si trova il file che PHP sta eseguendo.

Se il PC sul quale programmiamo e utilizziamo Visual Studio Code è lo stesso che esegue l'interprete PHP e non stiamo usando Docker, Vagrant o altre soluzioni di virtualizzazione tutto avviene automaticamente. In caso contrario, dobbiamo configurare manualmente il mapping dei percorsi. Ho mostrato la procedura esatta per Visual Studio Code e phpStorm

L'idea generale è quella di indicare il percorso dei file sull'ambiente che esegue materialmente lo script (Vagrant, Docker, VM o server remoto) e indicare all'IDE dove si trovi tale cartella sul PC locale.

PHP/Xdebug non si ferma ai breakpoint, Soluzione 7: Bloccato dal firewall

Se stiamo lavorando in una configurazione di "debug locale" in cui, però, l'interprete PHP è in esecuzione all'interno di Docker, Vagrant, altre soluzioni di virtualizzazione oppure su di un altro PC della rete locale, il problema potrebbe essere causato dal firewall del PC locale (quello sul quale è in esecuzione l'IDE) che, forse, sta bloccando la connessione.

In tal caso, assicuriamoci che il firewall lasci passare il traffico destinato alla porta sulla quale è in ascolto l'IDE:

• con Windows: Guida: come aprire le porte su Windows Firewall
• con Ubuntu: Configurare il firewall di Ubuntu (ufw) tramite interfaccia grafica: guida semplice a Gufw

PHP/Xdebug non si ferma ai breakpoint, Soluzione 8: Nessun breakpoint raggiunto

Un'altra circostanza da non sottovalutare: potremmo non aver definito nemmeno un breakpoint, oppure aver inserito il breakpoint in una riga che non raggiunta durante l'esecuzione.

Per far fonte a tale circostanza, raccomando di inserire un breakpoint sulla primissima riga del file PHP dell'applicazione oppure, ancora meglio, attivazione la funzione "interrompi sulla prima riga" come mostrato per Visual Studio Code oppure phpStorm

Conclusioni

In questa guida abbiamo visto cosa fare quando Xdebug non funziona e PHP non si ferma ai breakpoint con Visual Studio Code o phpStorm. Si tratta di un problema piuttosto comune, che si verifica spessissimo soprattutto mentre stiamo configurando il debugging di un progetto per la prima volta. Con un po' di pazienza, comunque, è generalmente facile risalire alla causa e applicare l'appropriata manovra correttiva.

I commenti qui sotto sono a disposizione per scambiarci esperienze e ulteriori soluzioni.