Sviluppo WordPress: 5 strumenti per il debug.

Durante lo sviluppo di un tema o di un plugin per WordPress è fondamentale avere a disposizione gli strumenti per individuare gli errori che si verificano durante l’esecuzione del codice.

Tra gli strumenti per il debug elencati di seguito, alcuni sono specifici di WordPress, altri sono applicabli a qualsiasi progetto PHP.

Dove possibile ho inserito i dettagli di configurazione, in altri casi le indicazioni sono generiche perchè legate all’ambiente di sviluppo utilizzato (sistema operativo, editor/IDE, etc…).

Questo elenco naturalmente non vuole definire uno standard, ma rispecchia semplicemente la mia “cassetta degli attrezzi” attuale. Nulla vieta di usare una configurazione diversa. In questo caso, se ti va, fammi sapere con un commento quali strumenti utilizzi.

Una nota importante: tutte le indicazioni riportate sono da intendersi esclusivamente per utilizzo in ambiente di sviluppo. Applicarle in produzione porta a potenziali problemi di sicurezza, poichè i messaggi di log possono esporre informazioni sensibili (credenziali, percorsi di sistema, etc…). Inoltre la scrittura e visualizzazione di grosse quantità di messaggi può avere impatto negativo sulle prestazioni dell’applicazione.

PHP: messaggi di errore e file di log

Il linguaggio alla base di WordPress fornisce alcune impostazioni per configurare la gestione degli errori.

Ho raccolto e configurato i parametri principali affinchè sia mostrato il maggior numero possibile di messaggi. Si trovano tutti nel file php.ini, il cui percorso dipende da vari fattori: per trovarlo puoi fare riferimento al risultato della funzione phpinfo() oppure verificare la documentazione dell’eventuale ambiente di sviluppo che stai usando (XAMPP, Laragon, etc…). In casi estremi, puoi ricorrere ad una ricerca nell’intero computer.

Ecco i parametri e la relativa configurazione:

; Attiva la visualizzazione degli errori.
display_errors = On
display_startup_errors = On

; Permette di scegliere quali tipologie di errore visualizzare.
; In questo caso mostra tutti gli errori, avvisi e notifiche.
; Tutti i valori possibili: https://www.php.net/manual/en/errorfunc.constants.php
error_reporting = E_ALL

; Attiva il log degli errori (anche quando la visualizzazione è disabilitata).
log_errors = On

; Indica il percorso e il nome del file in cui vengono salvati i messaggi di errore.
error_log = "/percorso/cartella/php_errors.log"

Con queste impostazioni sarà possibile vedere gli errori in diversi posti:

• nella pagina visualizzata dal browser
• nel file di log indicato
• nel file di log di WordPress (vedi paragrafo successivo)

WordPress: attivare la modalità debug

WordPress consente di attivare una propria modalità di debug che prevede la visualizzazione degli errori di PHP come indicato nel paragrafo precedente, ma anche di una serie di messaggi interni come, ad esempio, gli avvisi relativi alle funzioni deprecate.

La configurazione prevede la definizione di specifiche costanti all’interno del file wp-config.php. Il codice seguente deve essere inserito prima della chiusura della sezione modificabile:

// Attiva il debug interno.
define( 'WP_DEBUG', true );

// Mostra i messaggi di errore sulla pagina visualizzata nel browser.
define( 'WP_DEBUG_DISPLAY', true );

// Scrive i messaggi in un file di log.
define( 'WP_DEBUG_LOG', true );

/* That's all, stop editing! Happy publishing. */

Con questa configurazione i messaggi saranno visibili nel browser e nel file /wp-content/debug.log che verrà creato (ricordati di eliminarlo prima di andare in produzione!).

In qualsiasi punto del codice puoi scrivere direttamente nel file di log utilizzando la funzione error_log():

// Scrivi un messaggio.
error_log( 'messaggio di testo' );

// Visualizza il valore di una variabile di tipo stringa o numerico.
error_log( 'Il valore della variabile num è: ' . $num );

// Visualizza il contenuto di un array o di un oggetto.
// Passando true come secondo parametro, l'output della funzione
// viene indirizzato nel file di log e non visualizzato nella pagina.
error_log( print_r( $object, true ) );

Maggiori informazioni sul debug di WordPress sono disponibili in questa pagina della documentazione ufficiale: https://wordpress.org/support/article/debugging-in-wordpress/.

WordPress: plugin Query Monitor

Query Monitor è un piccolo (si fa per dire) gioiello che fornisce una enorme quantità di informazioni di debug direttamente all’interno della dashboard di WordPress.

Un elemento posto nell’admin bar mostra i tempi di esecuzione della pagina corrente e una serie di link che aprono le sezioni di un pannello a comparsa molto simile agli strumenti di sviluppo dei browser.

Tra le verie cose è possibile analizzare le query eseguite, gli hook utilizzati, i dati delle richieste HTTP e molto altro, tutto in modo molto dettagliato. Con opportuna configurazione è perfino in grado di aprire il file coinvolto in una certa operazione direttamente nel tuo editor e puntando all’esatto numero di riga.

All’inizio può sembrare quasi eccessivo per la quantità di informazioni riportate, ma merita senza dubbio un piccolo sforzo per prendere confidenza.

Difficile elencarne tutte le caratteristiche, per cui ti lascio i riferimenti alle pagine ufficiali:

• Plugin su WordPress: https://wordpress.org/plugins/query-monitor/
• Sito ufficiale: https://querymonitor.com/

Browser: developer tools

Non bisogna dimenticare che sviluppare su WordPress coinvolge anche altri linguaggi: HTML, CSS e Javascript.

In questi casi non si può prescindere dagli strumenti di sviluppo forniti dai browser.

Anche in questo caso le funzionalità sono moltissime ma, restringendo il campo alla sola individuazione degli errori, è necessario tenere sotto controllo almeno questi strumenti:

• la console che visualizza tutti i messaggi provenienti dalla pagina visualizzata
• il debugger Javascript
• la sezione relativa alla rete, in cui analizzare il contenuto inviato e ricevuto con le chiamate ajax.

Ecco i riferimenti alla documentazione ufficiale dei browser principali:

• Firefox: https://developer.mozilla.org/en-US/docs/Tools/
• Chrome: https://developers.google.com/web/tools/chrome-devtools/
• Edge: https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/
• Safari: https://developer.apple.com/safari/tools/

PHP: Xdebug

Torniamo infine a PHP, con questo punto che ho volutamente lasciato per ultimo in quanto più avanzato.

Con Xdebug hai accesso a molte funzionalità, ma riassumendo ti consente di:

• interrompere l’esecuzione del codice inserendo opportuni breakpoint.
• intercettare le interruzioni dovute ad errori.
• analizzare variabili ed oggetti durante le interruzioni.

Xdebug è un’estensione per PHP che va installata e configurata. Le modalità cambiano in base al sistema operativo e alla versione di PHP.

Inoltre, per utilizzarlo nel modo più comodo e completo, deve essere integrato con l’editor/IDE che utilizzi.

Non potendo fornire istruzioni specifiche, per avere maggiori dettagli ti suggerisco di consultare la documentazione ufficiale disponibile sul sito del progetto: https://xdebug.org/.