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

Xdebug è un componente aggiuntivo (gratuito) che consente di svolgere il debugging degli script PHP. Dopo averlo installato e configurato sul PC o server Ubuntu, potremo sfruttarlo tramite il nostro ambiente di sviluppo (IDE) preferito (phpStorm, Visual Studio Code ecc.) per fermare l'applicazione in qualsiasi punto (breakpoint) ed analizzare la situazione, eseguire le singole righe (step-by-step), ispezionare le variabili e, in generale, facilitare l'individuazione e la risoluzione dei bug. Vediamo allora come installare e configurare Xdebug su Ubuntu

Debug di pagine PHP con Xdebug: come funziona

Prima di entrare nel vivo della trattazione, è importante capire come funziona il debug di 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 capire è che la porta TCP/9003 viene aperta dall'IDE. Questo ha una conseguenza diretta: è Xdebug che si connette a Visual Studio Code, phpStorm ecc., e non viceversa!

Non è dunque necessario che il sistema sul quale è in esecuzione l'ambiente di sviluppo 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 l'IDE renda accessibile la propria porta TCP/9003 a quello con PHP e Xdebug.

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

Passo 1: Connessione SSH o Terminale locale

Lo ripeto ancora una volta per la massima chiarezza: non è necessario che il PC sul quale programmiamo (quello con Visual Studio Code, phpStorm ecc.) sia lo stesso che eroga fisicamente le pagine PHP. È sicuramente possibile che si tratti di PC differenti e, magari, dotati di sistemi operativi differenti. La procedura seguente va svolta solo sul PC o server che eroga le pagine PHP, non su quello con il nostro IDE.

In tal caso, il primo passo da svolgere è la connessione tramite SSH:

» Leggi: SSH con Windows, Linux, Mac: la Guida Definitiva - Come accedere ad un VPS, server cloud AWS/Azure o server aziendale con facilità

Se però abbiamo installato tutto sul PC locale (sia il webserver, sia l'interprete PHP, sia l'IDE), l'uso di SSH non è necessario. Limitiamoci ad aprire il Terminale ed impartire i comandi indicati di seguito sul computer locale.

Passo 2: Installare PHP

Xdebug è un componente che si integra con PHP. Prima di installare e configurare Xdebug, è quindi importante aver già predisposto l'interprete PHP ed il webserver. Le istruzioni passo per passo sono state fornite in quest'altra guida:

» Leggi: Guida: come installare PHP su Linux Ubuntu e CentOS (PHP-FPM)

Raccomando caldamente di non procedere all'installazione di Xdebug fino a quando non si è completata la configurazione di PHP, e solo dopo aver verificato che il webserver funzioni correttamente ed eroghi le pagine PHP come ci aspettiamo.

Passo 3: Diventare root

Dovete ora acquisire i privilegi massimi diventando root. Il comando è:

sudo -s

In caso dovesse esservi richiesta la password, digitate quella dell'account corrente.

» Leggi anche: Linux (Ubuntu) e sudo: come disabilitare la richiesta di password quando si eseguono comandi come root

In alternativa, potete utilizzare l'utente corrente ed anteporre sudo ad ogni comando mostrato di seguito.... ma divenire immediatamente root è molto più comodo.

Passo 4: Installare Xdebug

Procediamo ora ad installare Xdebug sul sistema che eroga le pagine PHP. Il comando è:

apt update && apt install php-xdebug -y

Arrivati a questo punto, Xdebug è attivo, ma non ancora configurato. Per verificarlo, creiamo un file di nome test.php nella cartella del nostro sito. Tale file deve contenere una sola riga:

<?php phpinfo();

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

Passo 5 (debug locale): Scaricare il file di configurazione

Se il PC sul quale programmiamo e utilizziamo l'ambiente di sviluppo è 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 su una macchina virtuale standard, ma sempre sul PC locale. Ancora: parliamo di "debug locale" anche quando PHP è in esecuzione su un PC diverso da quello dell'ambiente di sviluppo, ma entrambi sono all'interno della stessa rete locale (LAN).

In tal caso, impartiamo questo comando per scaricare il file di configurazione appropriato:

apt install curl -y && curl -Lo /etc/php/xdebug.ini https://turbolab.it/scarica/373

Passo 5 (debug remoto): Scaricare il file di configurazione

[ questo passo è ALTERNATIVO al precedente: dobbiamo svolgere l'uno oppure l'altro, a seconda della nostra situazione, ma non entrambi ]

Nel caso in cui il PC sul quale programmiamo e utilizziamo l'IDE e quello che esegue PHP siano realmente "remoti", ovvero siano separati da Internet, siamo nello scenario di debug remoto. In tal caso, dobbiamo utilizzare un file di configurazione differente. Impartiamo questo comando per scaricarlo:

apt update && apt install curl -y && curl -Lo /etc/php/xdebug.ini https://turbolab.it/scarica/374

Passo 6: Attivare la configurazione di Xdebug

Procediamo ora ad attivare il file di configurazione di Xdebug pronto all'uso che abbiamo appena scaricato. Allo scopo, è sufficiente creare un link nella cartella di configurazione di PHP.

Sempre lavorando sul sistema che eroga le pagine PHP, impartiamo questo lungo comando concatenato:

export PHP_VER="8.0" && ln -s /etc/php/xdebug.ini /etc/php/${PHP_VER}/fpm/conf.d/99-xdebug.ini && ln -s /etc/php/xdebug.ini /etc/php/${PHP_VER}/cli/conf.d/99-xdebug.ini && systemctl restart php${PHP_VER}-fpm

Nota importante: la variabile PHP_VER="8.0", valorizzata nel comando di cui sopra, fa sì che venga configurato Xdebug con PHP 8.0. Chi desiderasse utilizzare Xdebug con una versione di PHP precedente, può usare:

• PHP_VER="7.4"
• PHP_VER="7.3"
• PHP_VER="7.2"

Le versioni ulteriormente antecedenti, come PHP 7.1, non sono supportate dal moderno Xdebug 3.

Passo 7: Configurare l'ambiente di sviluppo

Arrivati fino a qui, PHP e Xdebug sono pronti. Dobbiamo ora procedere a configurare l'IDE affinché accetti la connessione da Xdebug. Allo scopo, seguiamo queste guide:

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

Passo 8: Risolvere i problemi

Prima o poi capita a tutti: abbiamo già installato correttamente Xdebug, configurato PHP e anche l'IDE, ma non è cambiato nulla! Le pagine PHP vengono caricate come al solito, l'esecuzione non si ferma sui breakpoint e non riusciamo a svolgere l'esecuzione step-by-step. In tal caso, consultiamo questo approfondimento:

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

Conclusioni

In questa guida abbiamo visto come installare Xdebug su Ubuntu in modo da eseguire il debugging delle pagine PHP. Personalmente, svolgo questa stessa procedura immediatamente su qualsiasi PC io debba programmare: l'utilizzo dello strumento di debugging per PHP migliora infatti enormemente la qualità del codice, riducendo i bug e, nello stesso tempo, abbatte drasticamente i tempi necessari allo sviluppo.