Come abilitare e configurare il modulo Xdebug in ServBay
ServBay, come potente ambiente locale per lo sviluppo web, offre agli sviluppatori PHP l’integrazione predefinita dello strumento di debug e analisi Xdebug. Abilitare Xdebug può migliorare notevolmente l’efficienza nello sviluppo di applicazioni PHP, consentendo un debug più comodo, analisi delle prestazioni e verifica della copertura del codice. In questa guida ti mostreremo come abilitare e configurare Xdebug in ServBay e come integrarlo con i principali ambienti di sviluppo integrato (IDE).
Panoramica del modulo Xdebug
Xdebug è un'estensione PHP ricca di funzionalità progettata per il debug e l'analisi del codice PHP. In ServBay, Xdebug è preinstallato, eliminando la necessità di compilazione o installazione manuale, e permettendo un’attivazione e una configurazione davvero semplici.
Funzionalità principali di Xdebug
- Debug a punti di interruzione: Consente di inserire breakpoints in corrispondenza di specifiche righe di codice; l’esecuzione del programma si arresta al breakpoint, permettendo di ispezionare lo stato delle variabili e lo stack delle chiamate passo dopo passo.
- Debug tramite stepping: Supporta l’esecuzione step-by-step del codice (Step Over), l’ingresso nelle funzioni (Step Into) e l’uscita dalle funzioni (Step Out), facilitando il tracciamento del flusso di esecuzione.
- Monitoraggio variabili: Visualizza in tempo reale i valori delle variabili locali e globali durante il debug.
- Tracciamento dello stack: Fornisce uno stack trace dettagliato in caso di errori o eccezioni, aiutando a individuare rapidamente la causa dei problemi.
- Analisi delle prestazioni (Profiling): Genera report sulle performance dell’esecuzione del codice, utili per individuare i colli di bottiglia.
- Analisi della copertura del codice: Misura la percentuale di codice eseguita dai test, aiutando a valutare l’efficacia dei test stessi.
Versioni integrate di Xdebug e mappatura delle porte in ServBay
ServBay preinstalla il modulo Xdebug per ogni versione di PHP disponibile. È importante notare che ciascuna versione di PHP utilizza una porta di ascolto Xdebug indipendente, correlata al numero di versione PHP: questo dettaglio è fondamentale per configurare il debugger nell’IDE.
Versione PHP | Versione Xdebug preinstallata | Porta di ascolto Xdebug predefinita |
---|---|---|
PHP 5.6 | Xdebug 2.5.5 | 39056 |
PHP 7.0 | Xdebug 2.5.5 | 39070 |
PHP 7.1 | Xdebug 2.5.5 | 39071 |
PHP 7.2 | Xdebug 3.1.6 | 39072 |
PHP 7.3 | Xdebug 3.1.6 | 39073 |
PHP 7.4 | Xdebug 3.1.6 | 39074 |
PHP 8.0 | Xdebug 3.3.1 | 39080 |
PHP 8.1 | Xdebug 3.4.0 | 39081 |
PHP 8.2 | Xdebug 3.4.0 | 39082 |
PHP 8.3 | Xdebug 3.4.0 | 39083 |
PHP 8.4 | Xdebug 3.4.0 | 39084 |
PHP 8.5 | Xdebug 3.4.0 | 39085 |
Regole sulle porte
La regola per la porta di ascolto di Xdebug è 39000 + numero di sottoversione PHP
. Ad esempio, per PHP 8.3 la porta sarà 39000 + 83 = 39083
, mentre per PHP 7.4 sarà 39000 + 74 = 39074
. Conoscere questa regola ti aiuta a identificare rapidamente la porta di Xdebug per diverse versioni di PHP.
Come abilitare il modulo Xdebug
Abilitare Xdebug in ServBay è estremamente semplice, soprattutto tramite l’interfaccia grafica (GUI) di ServBay. In alternativa, puoi modificare i file di configurazione manualmente.
Abilitazione tramite GUI di ServBay
Questo è il metodo più semplice e veloce.
- Apri l’interfaccia dell’applicazione ServBay.
- Nella barra di navigazione a sinistra, seleziona
Linguaggi
(Languages). - Espandi la sezione
PHP
e trova la versione PHP in cui vuoi abilitare Xdebug, ad esempioPHP 8.3
. - Clicca sul pulsante
Estensioni
accanto alla versione prescelta. - Nella lista delle estensioni che appare, trova il modulo
Xdebug
. - Attiva l’interruttore a sinistra di
Xdebug
per passare da spento a acceso. - Modifica eventuali parametri se necessario.
- Premi il pulsante
Salva
in basso nell’interfaccia. - ServBay riavvierà automaticamente il processo PHP e caricherà il modulo.
Figura: Abilitazione di Xdebug tra le estensioni
Verificare che Xdebug sia stato caricato con successo
Il metodo più affidabile è controllare le informazioni di configurazione PHP usando la funzione phpinfo()
.
- Nella root del sito ServBay (di default
/Applications/ServBay/www
) crea un file PHP semplice, ad esempiophpinfo.php
. - Inserisci nel file
phpinfo.php
il seguente codice:php<?php phpinfo(); ?>
1
2
3 - Accedi a questo file tramite il browser, ad esempio
https://servbay.demo/phpinfo.php
(sostituisciservbay.demo
con il dominio che hai configurato su ServBay). - Nella pagina di output di
phpinfo
cerca la sezione "Xdebug". Se il modulo è stato caricato correttamente, troverai una sezione dedicata con informazioni dettagliate sulla versione e sui parametri di configurazione.
Figura: Ricerca delle informazioni su Xdebug nell’output di phpinfo
Configurazione di Xdebug nell’IDE per il debugging
Abilitare Xdebug è solo il primo passo: per il debugging a breakpoint nell’IDE è necessario anche configurare l’interprete PHP, il debugger e il mapping del server. Di seguito troverai le istruzioni per PHPStorm e Visual Studio Code (VS Code).
Configurazione di Xdebug in PHPStorm
PHPStorm offre un supporto completo per Xdebug.
Apri le impostazioni di PHPStorm: Avvia PHPStorm e vai su
File
->Settings
(Windows/Linux) oPHPStorm
->Preferences
(macOS).Configura l’interprete PHP CLI:
- Naviga su
Languages & Frameworks
->PHP
. - Nella sezione
CLI Interpreter
, clicca il pulsante...
a destra. - Nella finestra che appare, clicca su
+
per aggiungere un nuovo interprete locale. - Seleziona il percorso dell’eseguibile PHP della versione desiderata su ServBay, ad esempio
/Applications/ServBay/package/php/8.3/8.3.7/bin/php
(il numero di versione potrebbe variare in base agli aggiornamenti di ServBay). - PHPStorm rileverà automaticamente versione ed estensioni, incluso Xdebug.
- Clicca su
OK
per salvare la configurazione.Figura: Configurare l’interprete CLI di PHP di ServBay in PHPStorm
- Naviga su
Configura i parametri di debug Xdebug:
- Vai su
Languages & Frameworks
->PHP
->Debug
. - Nel campo
Xdebug
, impostaDebug Port
sulla porta Xdebug corrispondente alla versione PHP scelta in ServBay (ad esempio, PHP 8.3 usa39083
). Assicurati che questa porta coincida con il valore dixdebug.client_port
. - Seleziona l’opzione
Can accept external connections
. - Premi
Apply
e poiOK
per salvare.Figura: Configurazione della porta di ascolto di Xdebug in PHPStorm
- Vai su
Configura il mapping del server web PHP:
- Naviga su
Languages & Frameworks
->PHP
->Servers
. - Clicca sul pulsante
+
a destra per aggiungere una nuova configurazione server. - Assegna un nome al server (ad esempio
ServBay Localhost
). - Imposta
Host
sul dominio configurato in ServBay (ad esempioservbay.demo
). - Imposta
Port
alla porta usata dal sito, solitamente443
(HTTPS) o80
(HTTP). - Scegli
Xdebug
come debugger. - Seleziona
Use path mappings
. - Configura il mapping tra il percorso locale del progetto (
Absolute path to local source
) e quello sul server (Absolute path on the server
). Se per esempio il progetto si trova in/Applications/ServBay/www/myproject
ed è accessibile dahttps://servbay.demo/
, il percorso locale/Applications/ServBay/www/myproject
deve mappare a/
sul server. Lo stesso vale per eventuali sottodomini comehttps://myproject.servbay.demo/
. - Clicca su
OK
per confermare.Figura: Configurazione di server e mapping dei percorsi in PHPStorm
- Naviga su
Avvia una sessione di debug:
- Apri il file PHP che desideri debuggare in PHPStorm.
- Imposta i breakpoints cliccando nell’area a sinistra dei numeri di riga (si attiverà un pallino rosso).
- Premi il pulsante
Start Listening for PHP Debug Connections
sulla barra degli strumenti superiore di PHPStorm (icona a forma di insetto). L’icona diventerà verde, indicando che l’ascolto è attivo. - Accedi via browser alla tua applicazione PHP (es.
https://servbay.demo/index.php
). - Se tutto sarà configurato correttamente, Xdebug si collegherà a PHPStorm, fermandosi ai breakpoint impostati e consentendo il debugging interattivo.
Figura: Avvio dell’ascolto Xdebug in PHPStorm
Configurazione di Xdebug in Visual Studio Code (VS Code)
Anche VS Code, tramite estensioni, supporta ottimamente il debugging con Xdebug.
Installa l’estensione PHP Debug:
- Apri VS Code.
- Vai alla vista Estensioni (
Ctrl+Shift+X
oCmd+Shift+X
). - Cerca “PHP Debug” ed installa l’estensione “by Felix Becker”.
Configura
launch.json
:- Apri la cartella del tuo progetto PHP.
- Passa alla sezione Esegui e Debug (
Ctrl+Shift+D
oCmd+Shift+D
). - Clicca sull’icona dell’ingranaggio in alto e scegli "PHP": questo genera un file
launch.json
sotto la cartella.vscode
nel root del progetto. - Modifica
launch.json
, assicurandoti che il parametroport
corrisponda a quello associato alla versione PHP in ServBay (ad esempio, PHP 8.3 usa39083
). - Configura il mapping dei percorsi (Path Mapping): Questo passaggio è fondamentale per il debugging in VS Code. Nel file
launch.json
aggiungi o modifica la sezionepathMappings
, mappando il percorso del progetto su ServBay con il percorso locale sul computer.jsonAdatta il mapping in base alla struttura del tuo progetto e alla configurazione dei siti ServBay.{ "version": "0.2.0", "configurations": [ { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 39083, // Modifica questa porta secondo la versione PHP "pathMappings": { // Mappa il percorso del progetto dalla root del sito ServBay // es. se il tuo progetto è in /Applications/ServBay/www/myproject // e vi accedi tramite https://servbay.demo/, la root '/' corrisponde alla tua root locale "/": "${workspaceRoot}" // Se il progetto è in /Applications/ServBay/www/myproject // e vi accedi tramite https://myproject.servbay.demo/ (sottodominio = sottocartella) // allora la root '/' corrisponde comunque alla root locale // "/": "${workspaceRoot}" // valido anche in questo caso } }, { "name": "Launch currently open script", "type": "php", "request": "launch", "program": "${file}", "cwd": "${fileDirname}", "port": 39083 // Modifica questa porta secondo la versione PHP } ] }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29${workspaceRoot}
indica, solitamente, la cartella principale del progetto aperta in VS Code.
Avvia una sessione di debugging:
- Apri il file PHP da debuggare in VS Code.
- Imposta i breakpoint cliccando a sinistra dei numeri di riga.
- Passa alla sezione Esegui e Debug (
Ctrl+Shift+D
oCmd+Shift+D
). - Seleziona dal menu a tendina di configurazione la voce "Listen for Xdebug".
- Clicca il pulsante verde di avvio debug. La barra di stato di VS Code diventerà arancione, indicando che Xdebug è in ascolto.
- Accedi tramite browser alla tua applicazione PHP. Se la configurazione è corretta, Xdebug si collegherà a VS Code e l’esecuzione si fermerà sui breakpoint.
FAQ (Domande Frequenti)
D: La sezione Xdebug non compare nella pagina
phpinfo()
?- R: Verifica di aver abilitato Xdebug dal GUI di ServBay o modificando manualmente
xdebug.ini
. - Assicurati di aver riavviato il servizio PHP interessato.
- Controlla che il percorso al file
xdebug.ini
sia corretto e che la rigazend_extension = xdebug.so
non sia commentata. - Consulta i log di ServBay (
/Applications/ServBay/logs/php/<version>/error.log
) per eventuali errori di caricamento di Xdebug.
- R: Verifica di aver abilitato Xdebug dal GUI di ServBay o modificando manualmente
D: Ho impostato i breakpoint nell’IDE ma il programma non si ferma?
- R: Assicurati che l’IDE sia in ascolto delle connessioni Xdebug (icona dell’insetto verde in PHPStorm, barra arancione in VS Code).
- Controlla che la porta di ascolto configurata nell’IDE corrisponda a
xdebug.client_port
e quella predefinita della relativa versione PHP in ServBay. - Verifica che il path mapping sia impostato correttamente: il percorso dei file sul server deve corrispondere a quello locale. Questo è spesso la causa principale di problemi di configurazione.
- Controlla le impostazioni di firewall — assicurati che non blocchino la porta di Xdebug (in genere porta nella serie
390xx
). - Se nel file
xdebug.ini
hai configuratoxdebug.start_with_request=trigger
, controlla che il browser o la richiesta includa il trigger (es. tramite l’estensione browser Xdebug helper o aggiungendo?XDEBUG_TRIGGER=1
nell’URL).
D: La connessione Xdebug si interrompe dopo un po’?
- R: Controlla i parametri
xdebug.remote_autostart
oxdebug.start_with_request
inxdebug.ini
. Se impostati suyes
, potrebbero far partire una sessione debug ad ogni richiesta: si consiglia la modalitàtrigger
. - Verifica le impostazioni di timeout dell’IDE; alcuni ambienti integrati prevedono limiti temporali di connessione.
- R: Controlla i parametri
Conclusione
ServBay facilita l’attivazione e la configurazione di Xdebug, abbassando notevolmente la barriera d’ingresso per gli sviluppatori PHP. Grazie alla GUI intuitiva o alla modifica manuale dei file di configurazione, puoi abilitare rapidamente Xdebug in diverse versioni di PHP con ServBay. Unito alle capacità di debug avanzate di PHPStorm e VS Code, avrai a disposizione uno strumento potente per il debug, l’ottimizzazione delle performance e il miglioramento della qualità del codice PHP — una risorsa essenziale per il tuo workflow di sviluppo locale. Saper sfruttare a pieno l’integrazione tra ServBay e Xdebug migliorerà sensibilmente la tua produttività nello sviluppo PHP.