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.

1. Apri l’interfaccia dell’applicazione ServBay.
2. Nella barra di navigazione a sinistra, seleziona Linguaggi (Languages).
3. Espandi la sezione PHP e trova la versione PHP in cui vuoi abilitare Xdebug, ad esempio PHP 8.3.
4. Clicca sul pulsante Estensioni accanto alla versione prescelta.
5. Nella lista delle estensioni che appare, trova il modulo Xdebug.
6. Attiva l’interruttore a sinistra di Xdebug per passare da spento a acceso.
7. Modifica eventuali parametri se necessario.
8. Premi il pulsante Salva in basso nell’interfaccia.
9. 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().

1. Nella root del sito ServBay (di default /Applications/ServBay/www) crea un file PHP semplice, ad esempio phpinfo.php.
2. Inserisci nel file phpinfo.php il seguente codice:

   <?php
   phpinfo();
   ?>

3. Accedi a questo file tramite il browser, ad esempio https://servbay.demo/phpinfo.php (sostituisci servbay.demo con il dominio che hai configurato su ServBay).
4. 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.

1. Apri le impostazioni di PHPStorm: Avvia PHPStorm e vai su File -> Settings (Windows/Linux) o PHPStorm -> Preferences (macOS).

2. 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

3. Configura i parametri di debug Xdebug:

   • Vai su Languages & Frameworks -> PHP -> Debug.
   • Nel campo Xdebug, imposta Debug Port sulla porta Xdebug corrispondente alla versione PHP scelta in ServBay (ad esempio, PHP 8.3 usa 39083). Assicurati che questa porta coincida con il valore di xdebug.client_port.
   • Seleziona l’opzione Can accept external connections.
   • Premi Apply e poi OK per salvare. Figura: Configurazione della porta di ascolto di Xdebug in PHPStorm

4. 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 esempio servbay.demo).
   • Imposta Port alla porta usata dal sito, solitamente 443 (HTTPS) o 80 (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 da https://servbay.demo/, il percorso locale /Applications/ServBay/www/myproject deve mappare a / sul server. Lo stesso vale per eventuali sottodomini come https://myproject.servbay.demo/.
   • Clicca su OK per confermare. Figura: Configurazione di server e mapping dei percorsi in PHPStorm

5. 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.

1. Installa l’estensione PHP Debug:

   • Apri VS Code.
   • Vai alla vista Estensioni (Ctrl+Shift+X o Cmd+Shift+X).
   • Cerca “PHP Debug” ed installa l’estensione “by Felix Becker”.

2. Configura launch.json:

   • Apri la cartella del tuo progetto PHP.
   • Passa alla sezione Esegui e Debug (Ctrl+Shift+D o Cmd+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 parametro port corrisponda a quello associato alla versione PHP in ServBay (ad esempio, PHP 8.3 usa 39083).
   • Configura il mapping dei percorsi (Path Mapping): Questo passaggio è fondamentale per il debugging in VS Code. Nel file launch.json aggiungi o modifica la sezione pathMappings, mappando il percorso del progetto su ServBay con il percorso locale sul computer.

     {
         "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
             }
         ]
     }

     Adatta il mapping in base alla struttura del tuo progetto e alla configurazione dei siti ServBay. ${workspaceRoot} indica, solitamente, la cartella principale del progetto aperta in VS Code.

3. 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 o Cmd+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 riga zend_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.

• 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 configurato xdebug.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 o xdebug.start_with_request in xdebug.ini. Se impostati su yes, 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.

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.