Guida a Xdebug con phpStorm: installazione, configurazione, breakpoint ed esecuzione a step - la Guida Definitiva al debug PHP

phpStorm è l'ambiente di sviluppo integrato (IDE) che molte aziende e programmatori professionisti utilizzano quotidianamente per sviluppare siti e applicazioni web in PHP. Fra le molte, ottime funzionalità offerte, phpStorm si integra perfettamente con Xdebug, permettendoci così di svolgere il debug dei file PHP sia sul nostro PC, sia in esecuzione su di un server remoto. Abbiamo così a disposizione lo stop sui breakpoint, l'esecuzione delle singole righe (step-by-step), l'ispezione delle variabili e tutto quello che serve per verificare i nostri applicativi, programmare meglio e più velocemente. In questa guida vedremo dunque come configurare phpStorm con Xdebug per eseguire il debugging degli script PHP, locali e remoti

La seguente procedura funziona con tutte le piattaforme supportate da phpStorm. Nello specifico, io l'ho svolta con Windows 10 e Linux (Ubuntu).

La trattazione è appunto incentrata su phpStorm e Xdebug. Per ottenere il medesimo risultato con Visual Studio Code, si veda quest'altro approfondimento dedicato:

» Leggi: Come configurare Xdebug e Visual Studio Code: la Guida Definitiva al debug PHP (con breakpoint ed esecuzione a step per Windows 10 e Linux)

Debug di pagine PHP con Xdebug: come funziona

Prima di entrare nel vivo della trattazione, è importante capire come funziona il debug dei file PHP tramite Xdebug:

1. Xdebug si integra con l'interprete PHP tramite un'estensione, da installare sullo stesso PC o server che esegue gli script PHP
2. Xdebug si connette all'IDE (l'ambiente di sviluppo, come Visual Studio Code, phpStorm ecc.) tramite una porta configurabile - di default è la TCP/9003
3. Xdebug invia all'IDE le informazioni necessarie affinché esso possa visualizzare lo stato dell'applicazione

Il concetto-chiave da portare a casa è che la porta viene aperta dall'IDE. Questo ha una conseguenza diretta: è Xdebug che si connette a phpStorm, e non viceversa!

Non è dunque necessario che il sistema sul quale è in esecuzione phpStorm sia lo stesso sul quale gira lo script PHP. Di più: il computer con l'ambiente di sviluppo potrebbe non avere nemmeno installato PHP e Xdebug, e i due computer potrebbero persino utilizzare un sistema operativo diverso.

L'unico vero requisito è che il PC sul quale gira phpStorm renda accessibile la porta a quello con PHP e Xdebug.

Capito questo, entriamo nel vivo dell'installazione di Xdebug.

Passo 1: Installare PHP e Xdebug

Per prima cosa, è necessario installare PHP e Xdebug su un PC o server. Lo ripeto ancora una volta per la massima chiarezza: non è necessario che il PC sul quale programmiamo con phpStorm sia lo stesso che eroga fisicamente le pagine PHP. È possibile che si tratti di PC differenti e, magari, dotati di sistemi operativi differenti. Xdebug va installato solo sul PC/server con PHP seguendo questa guida:

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

Passo 2 (solo per il debug remoto): SSH e RemoteForward

Se il PC sul quale programmiamo e utilizziamo phpStorm è lo stesso che esegue l'interprete PHP, siamo in una situazione di debug locale. Lo stesso dicasi se l'interprete PHP è in esecuzione all'interno di Docker, Vagrant, oppure all'interno di macchina virtuale, ma sempre sul PC locale. Ancora: parliamo di "debug locale" anche quando PHP è in esecuzione su un PC diverso da quello di phpStorm, ma entrambi sono all'interno della stessa rete locale (LAN). In tal caso, possiamo saltare al Passo successivo.

Se però il PC con phpStorm e quello che esegue PHP sono realmente "remoti", ovvero separati da Internet, siamo nello scenario di debug remoto. In tal caso, dobbiamo configurare, sul PC locale con phpStorm, un tunnel SSH che permetta di esporre la porta di phpStorm al sistema remoto: è quella alla quale Xdebug si connetterà per abilitare la magia del debugging.

Allo scopo, dobbiamo creare un "profilo" di connessione SSH all'interno del nostro file .ssh/config come dettagliato in quest'altro approfondimento:

» Leggi: [guida] Come configurare la connessione SSH con tunnel, proxy e chiavi diverse: guida al file .ssh/config (con esempi pratici, Windows 10 e Linux)

In particolare, vogliamo aggiungere una direttiva come questa:

RemoteForward 9003 localhost:9001

Così facendo, la porta locale 9001 del PC con phpStorm diverrà contattabile dal server con PHP e Xdebug sulla sua porta 9003 (utilizzata di default da Xdebug). Il risultato ultimo sarà simile a questo:

Host azienda

Hostname utenti.mia-azienda.com

User pippo

RemoteForward 9003 localhost:9001

Di nuovo: fate riferimento alla guida dedicata a .ssh/config per le istruzioni passo passo alla creazione di questo "profilo".

Una volta preparato il profilo, dovremo sempre connetterci in SSH e rimanere connessi affinché il debugging con Xdebug possa funzionare.

Passo 3: Installare phpStorm e PHP Debug

Se ancora non l'abbiamo fatto, procediamo a scaricare e installare l'IDE:

» Download: phpStorm (Windows, Linux, Mac)

Procediamo poi ad aprire, tramite phpStorm, la cartella locale che contiene il codice del nostro progetto

Passo 4: Modificare la porta di Xdebug

Procediamo cliccando la voce di menu File -> Settings. Dal pannello apertosi, cerchiamo xdebug tramite il campetto in alto a sinistra, poi sul nodo Debug

Da qui, rivolgiamo l'attenzione alla sezione Xdebug nella schermata principale. Vogliamo assicurarci che che il campo Debug port legga 9000,9003,9001

In realtà, questa modifica è necessaria solo se abbiamo aperto un tunnel SSH per il debug remoto seguendo la configurazione consigliata in precedenza. Raccomando di farlo subito comunque, anche se siamo in una situazione di debug locale: non ci sono controindicazioni e, in caso passassimo al debug remoto in seguito, phpStorm sarà già pronto.

Mantenete aperta la finestra perché dobbiamo cambiare un altro settaggio.

Passo 5: Sospensione all'avvio (Break at first line)

Trovo sia molto importante attivare l'opzione che fa sì che l'esecuzione venga sospesa automaticamente sulla primissima riga del primo file PHP eseguito. Allo scopo, basta attivare l'opzione Break at first line in PHP scripts

In seguito, quando avremo verificato che tutto funzioni correttamente, potremo valutare di disattivare questa opzione.

Confermiamo e chiudiamo la finestra cliccando OK.

Passo 6: Avviare la sessione dei debug

Ora è (quasi) tutto pronto: possiamo avviare la sessione di debug! Allo scopo, clicchiamo sulla piccola icona raffigurante il telefono con il bug che si trova in alto a destra. Vogliamo che siano visibili le onde che escono dalla cornetta, cioè senza il segnale di divieto rosso sopra

Se stiamo usando Windows 10, Windows Firewall ci chiederà di autorizzare l'applicazione. Spuntiamo entrambe le caselle e confermiamo

» Leggi anche: TLI risponde: cosa significa che "Windows Firewall ha bloccato alcune funzionalità di questa app"?

phpStorm entra così in modalità "ascolto" (listening). Sta cioè attendendo che Xdebug si connetta per iniziare l'attività di debugging.

Per far sì che questo accada, è sufficiente aprire il browser web e... navigare il nostro sito!

Passo 7: Specificare i percorsi (path Mappings)

Se la configurazione è stata svolta correttamente, phpStorm mostrerà la finestra dal titolo Incoming Connection From Xdebug: è il segnale che Xdebug sta effettivamente cercando di connettersi a phpStorm, e tutto sta funzionando come ci aspettiamo.

Da questa schermata, limitiamoci a selezionare il file sul disco locale che contiene il codice PHP della pagina che stiamo aprendo via browser web

Da qui, clicchiamo Accept. Poiché abbiamo configurato il debugger di modo che si fermi alla prima riga, l'esecuzione dovrebbe essere sospesa immediatamente

In caso l'esecuzione proceda come al solito, senza che lo script si fermi sulla prima riga, abbiamo un problema. Ho proposto alcune idee per risolverlo in quest'altro approfondimento:

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

Se invece l'esecuzione si è correttamente fermata sulla prima riga, significa che tutto è stato configurato correttamente. Dallo stato di sospensione attuale possiamo fare tante cose belle.

Passo 8: Variabili e stack delle chiamate

Per prima cosa, rivolgiamo l'attenzione in basso a sinistra e clicchiamo sulla tab Debugger.

Da qui, notiamo la sezione sulla destra, denominata Variables: contiene tutte le variabili definite dall'applicazione, ed il loro valore. Nell'esempio seguente, ad esempio, è definita la variabile globale $_SERVER. Essendo di tipo array, possiamo espandere il nodo e visualizzare le chiavi e i valori che contiene

Mano a mano che procederemo con l'esecuzione dello script (v. seguito), verranno mostrate qui anche le altre variabili definite ed, eventualmente, valorizzate

Cliccando sul piccolo + nella striscia di comandi alla sinistra delle variabili possiamo aggiungere dei "watch", ovvero variabili ed espressioni che desideriamo tenere sott'occhio. Il loro valore verrà mostrato qui e aggiornato mano a mano che proseguiremo con l'esecuzione dello script PHP.

Nella sezione di sinistra, chiamata Frames, troviamo lo stack delle chiamate: mostra il flusso delle chiamate alle varie funzioni e l'invocazione dei metodi. In pratica, si parte sempre con un {main} che costituisce la pagina principale, poi ogni riga indica una chiamata. Oltre ad aiutarci a capire il flusso del programma ("chi chiama chi"), questa sezione è utilissima perché possiamo sempre cliccare sulle singole righe per aprire automaticamente il file che contiene il codice in questione e saltare immediatamente alla riga in cui è avvenuta la chiamata.

Passo 9: Breakpoint e avanzamento a step

In abbinata a Xdebug, phpStorm offre la possibilità di inserire molteplici breakpoint, ovvero punti in cui l'esecuzione dello script PHP deve essere sospesa per consentirci di ispezionare le variabili, lo stack delle chiamate e lo stato dell'applicazione.

Per impostare un breakpoint con phpStorm è sufficiente:

1. aprire il file che contiene il punto in cui vogliamo sospendere l'esecuzione dell'applicazione
2. individuare la riga alla quale vogliamo sospendere l'esecuzione
3. cliccare sullo spazio vuoto che si trova subito prima al numero di riga in questione

Apparirà così un pallino rosso, segnale che il breakpoint è impostato

Ora che abbiamo capito come inserire un breakpoint, dobbiamo individuare i due pulsanti "play" e "stop" che si trovano sulla sinistra

Il primo, quello con la freccia verde, è il "play": continua con l'esecuzione, fermandosi solo al breakpoint successivo. Se non è definito alcun breakpoint dopo la posizione corrente, l'applicazione procede fino alla fine.

Il quadrato rosso è lo "stop": termina la sessione di debug.

L'altra serie di pulsanti che permette di avanzare con l'esecuzione si trovano nella barra subito sopra alla lista delle variabili

Questi pulsanti permettono di avanzare con l'esecuzione del programma in vari modi:

1. Step over (F8): esegue la prossima istruzione, poi si ferma di nuovo. Questo è il comando che useremo più spesso per avanzare "un passo alla volta"
2. Step into (F7): è simile al precedente, ma con una sostanziale differenza. Se la prossima istruzione è una chiamata a funzione oppure l'invocazione di un metodo, il debugger entra nel codice in questione, poi si ferma di nuovo, di modo che sia possibile procedere con l'esecuzione a step della funzione/metodo in questione. Questo è l'altro comando che useremo spesso
3. Force step into (Alt+Maiusc+F7): il comando precedente, Step into, non entra in alcune chiamate. Questo, al contrario, entra sempre in qualsiasi chiamata
4. Step out (Maiusc+F8): procede nell'esecuzione della funzione/metodo corrente, poi esce e si ferma di nuovo.
5. Run to cursor (Alt+F9): procede con l'esecuzione e si ferma nel punto in cui è attualmente posizionato il cursore di inserimento testo

Passo 10: Esaminare le variabili nella finestra

Un'altra cosina che mi piace moltissimo di phpStorm è la possibilità di esaminare le variabili usando una finestrella dedicata:

1. fare click con il pulsante destro del mouse su una variabile
2. dal menu a tendina apertosi, scegliere Evaluate Expression...

Si apre così una finestra nella quale viene mostrato il valore della variabile

Quando si lavora con oggetti, array o altre strutture dati molto articolate, con svariati livelli di annidamento e incapsulamento, questa finestra permette di analizzare i valori con grande comodità.

Passo 11: Breakpoint condizionali

Immaginiamo di eseguire un lungo ciclo for su centinaia di migliaia di valori. Uno di questo causa problemi al resto dell'applicazione, e vorremmo esaminare il perché tramite il debugger. Raggiungere il punto in cui si verifica la condizione specifica con i breakpoint "normali" sarebbe estremamente noioso, perché dovremmo manualmente ispezionare, appunto, centinaia di migliaia di valori prima di trovare quello giusto. Per gestire questa necessità si usano i breakpoint condizionali, che sospendono l'esecuzione solo quando si verifica una determinata condizione.

Per inserire un breakpoint condizionale con phpStorm:

• inserire un breakpoint "normale" nel punto desiderato
• fare click con il pulsante destro del mouse sul breakpoint appena aggiunto
• dalla finestra apertasi, digitare l'espressione che, quando vera, sospende l'esecuzione
• cliccare Done per confermare

Nell'esempio sottostante ho inserito un breakpoint condizionale alla riga 12 sulla condizione $name == "zane". Poiché la variabile è stata così valorizzata alla precedente riga 8, l'esecuzione verrà sospesa

Conclusioni

In questa guida abbiamo visto come eseguire il debug del codice PHP in phpStorm tramite Xdebug. La vera complessità dell'operazione risiede nella corretta configurazione e integrazione di Xdebug con l'interprete PHP. Da lì in poi, però, la configurazione di phpStorm è piuttosto semplice, e va svolta soltanto la prima volta per ogni progetto.

Buon debugging!