Debug Log di WordPress, cos’è e come abilitarlo

Il log è un file di registro, trovi una guida a riguardo. In un web server diversi applicativi generano un log, quindi si possono trovare tanti file di log, solitamente nella cartella /var/log/ su hosting linux.

Nel web server che ospita questo blog, ad esempio, c’è il log di Nginx, PHP, MySQL e molti altri. Anche WordPress ha il suo log, ma in genere è disattivato.

Il log di WordPress registra avvisi ed errori generati dal CMS (e dai rispettivi plugin attivi e temi installati) e serve per fare debugging su server locali o di sviluppo.

Tutti i developer lo sanno: spesso le cose non vanno come previsto. Più complesso e sofisticato è il codice che stai utilizzando per customizzare il tuo sito web WordPress e maggiori sono le possibilità che qualcosa vada storto.

Debug in WordPress

Il debug del codice PHP e delle chiamate AJAX fa parte di qualsiasi progetto basato su WordPress, e questo CMS viene fornito con specifici sistemi di debug progettati per aiutare che sviluppa plugin e temi a standardizzare il codice ed evitare errori.

Nel mio caso faccio una sessione di debug dei vari log ogni volta che cambio parti di codice PHP di un tema o di un plugin, in modo da verificare che non ci siano errori che possono impattare negativamente sull’usabilità o le prestazioni.

Debug mode di WordPress

I problemi nel codice sono spesso chiamati “bug”: possono causare qualsiasi cosa, da scarse prestazioni alla visualizzazione di errori fino all’arresto totale del sito web. In alcuni casi, il codice non è propriamente errato, ma può andare in conflitto con altri pezzi di codice.

Il CMS WordPress è attivo e in sviluppo ormai da molti anni. La versione 1.0 fu rilasciata a gennaio 2004 e, grazie a cicli di aggiornamento offre una serie di funzionalità in gran parte prive di errori. Tuttavia, al crescere della complessità del sito web, i vari plugin utilizzati ed eventuali customizzazioni su larga scala possono causare conflitti, rallentamenti ed errori.

La modalità di debug di WordPress offre un modo per identificare questi problemi mentre si verificano e aiuta ad identificare l’origine dei problemi.

Come abilitare il log di debug di WordPress

Il codice seguente, inserito nel file wp-config.php, abilita la scrittura del log di debug. Il log contiene tutti gli errori e gli avvisi generati da WordPress, e lo troverai nella directory wp-content con il nome file debug.log.

Inoltre, il codice di esempio nasconde gli errori in modo che non compaiano nelle pagine HTML (WP_DEBUG_DISPLAY) ma solo nel log.

// Abilita la modalità WP_DEBUG
define( 'WP_DEBUG', true );

// Abilita il log /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Disabilita la stampa degli errori e avvisi a schermo
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Usa la versione di sviluppo dei file JS e CSS (serve solo se hai modificato i file core)
define( 'SCRIPT_DEBUG', true );

Il log è in molti casi un lungo file di testo, che può essere analizzato con software specifici per l’analisi dei log, ma anche con Excel. Ad inizio articolo ho messo un link ad una guida che spiega come fare.

WP_DEBUG

WP_DEBUG è una costante PHP (una variabile globale permanente) che può essere utilizzata per attivare la modalità “debug” in WordPress. Si presume che sia false per impostazione predefinita e di solito è impostato su true nel file wp-config.php sulle copie di sviluppo di WordPress.

// Abilita il debugging.
define( 'WP_DEBUG', true );

// Disabilita il debugging.
define( 'WP_DEBUG', false );

I true e false nell’esempio non sono circondati da apostrofi (‘) perché sono valori booleani (vero/falso). Se imposti le costanti su “false”, verranno interpretate come vere perché le virgolette ne fanno una stringa anziché un valore booleano.

Non è consigliabile utilizzare WP_DEBUG o altri strumenti di debug su siti live; sono pensati per test locali e installazioni di staging.

Abilitare WP_DEBUG causa la visualizzazione di tutti gli errori e avvisi PHP. È probabile che ciò modifichi il comportamento predefinito di PHP che visualizza solo errori fatali e/o mostra una schermata bianca quando vengono raggiunti gli errori. Mostrare tutti gli avvisi PHP spesso genera messaggi per cose che non sembrano guaste, ma non seguono le convenzioni di convalida corrette dei dati all’interno di PHP. Questi avvisi sono facili da correggere una volta identificato il codice pertinente e il codice risultante è quasi sempre più resistente ai bug e più facile da mantenere.

WP_DEBUG avvisa anche su funzioni e argomenti deprecati di WordPress che vengono utilizzati sul tuo sito. Si tratta di funzioni o argomenti di funzione che non sono stati ancora rimossi dal codice principale, ma che verranno eliminati nel prossimo futuro. Gli avvisi di deprecazione (deprecation notices) spesso indicano la nuova funzione che dovrebbe essere utilizzata al suo posto.

Per disabilitare la modalità debug dovrai semplicemente cambiare WP_DEBUG da true a false.

WP_DEBUG_LOG

WP_DEBUG_LOG lavora insieme a WP_DEBUG e fa in modo che tutti gli errori vengano salvati anche in un file di registro chiamato debug.log. Se non abiliti WP_DEBUG non funziona WP_DEBUG_LOG.

Avere il file è utile se si desidera rivedere tutti gli avvisi in un secondo momento o se è necessario visualizzare gli avvisi generati fuori schermo (ad esempio durante una richiesta AJAX o wp-cron run). Questo ti consente di scrivere nel file di registro utilizzando la funzione error_log() incorporata in PHP, che può essere utile, ad esempio, durante il debug di eventi Ajax.

Se impostato su true, il registro viene salvato in wp-content/debug.log all’interno del filesystem del tuo sito. In alternativa, puoi impostarlo su un percorso file valido per salvare il file altrove.

define( 'WP_DEBUG_LOG', true );
// OPPURE puoi definire una cartella diversa da quella di default
define( 'WP_DEBUG_LOG', '/tmp/wp-errors.log' );

Ricordati che:

• affinché WP_DEBUG_LOG esegua qualsiasi cosa, WP_DEBUG deve essere abilitato (true)
• puoi disattivare WP_DEBUG_DISPLAY in modo indipendente.

WP_DEBUG_DISPLAY

Anche WP_DEBUG_DISPLAY dipende dall’abilitazione di WP_DEBUG e permette di inserire nell’HTML delle pagine i messaggi di debug. L’impostazione predefinita è true, quindi mostra errori e avvisi man mano che vengono generati. L’impostazione su false nasconde tutti gli errori. Questo comando dovrebbe essere usato insieme a WP_DEBUG_LOG in modo che gli errori possano essere rivisti in seguito.

define( 'WP_DEBUG_DISPLAY', false );

Ricordati che:

• affinché WP_DEBUG_DISPLAY possa fare qualsiasi cosa, WP_DEBUG deve essere abilitato (true)
• puoi controllare WP_DEBUG_LOG in modo indipendente.

Abilitare la stampa a schermo degli errori introduce potenziali rischi. I più preoccupanti sono i problemi di sicurezza; se la modalità WP_DEBUG_DISPLAY è attivata su siti live, hacker malintenzionati possono vedere le operazioni svolte dal codice, e magari usare exploit per accedere alla macchina. Se possono quindi compromettere gli ambienti amministrativi, potrebbero essere in grado di inserire nuovo codice malevolo oppure rubare i dati del sito o installare “backdoor” che consentono l’accesso a lungo termine.

Usa WP_DEBUG_DISPLAY solo su siti in hosting locale o chiusi in sviluppo!

SCRIPT_DEBUG

SCRIPT_DEBUG è una costante correlata che forza WordPress ad utilizzare le versioni “dev” dei file CSS e JavaScript di base anziché le versioni ridotte (minificate) che vengono normalmente caricate nei siti live. Questo torna utile quando vuoi verificare al volo le modifiche a qualsiasi file .js o .css integrato. L’impostazione predefinita è false.

define( 'SCRIPT_DEBUG', true );

Plugin per il debugging

Esistono numerosi plugin di WordPress per aiutare a gestire la modalità di debug. Due dei più popolari sono Query Monitor e Debug Bar; entrambi consentono di attivare facilmente la modalità di debug in WordPress ma offrono anche funzionalità aggiuntive.

Nel caso di Query Monitor, le funzionalità di debug vengono estese per includere chiamate Ajax, chiamate API REST e controlli delle capacità dell’utente.

Debug Bar aggiunge un menu di debug alla barra di amministrazione di WordPress che visualizza query, cache e informazioni di debug aggiuntive a colpo d’occhio per semplificare il processo.

Fare debug di WordPress è importante!

Se stai sviluppando il tuo plug-in o progettando un nuovo tema per Web WordPress da zero, potresti riscontrare conflitti di codice che potrebbero influire negativamente sulle prestazioni o addirittura paralizzare i siti su larga scala. La modalità di debug di WordPress consente di identificare questi problemi prima che il tuo sito o servizio diventi attivo, riducendo a sua volta il tempo e lo sforzo necessari per trovare e risolvere potenziali problemi.