Come attivare il Debug di WordPress, opzioni avanzate e approfondimenti

Aggiornamento e riadattamento di un articolo originale del 24 Aprile 2013

Breve introduzione al debug di WordPress

Il debug è una modalità di WordPress, normalmente disattivata, che serve ad individuare le possibili cause di errori in caso di malfunzionamenti di un sito WordPress.

È sicuramente il miglior strumento di diagnostica che il nostro CMS preferito mette a disposizione, senza dover ricorrere a strumenti esterni o a plugin.

Utile in caso di malfunzionamenti, o  per la verifica del codice in fase di sviluppo di soluzioni, in generale per la verifica del corretto funzionamento di un sito WordPress.

Come attivare il debug di WordPress

Il debug di WordPress si attiva direttamente nel file di configurazione di WordPress wp-config.php.

Prima di modificare il file di configurazione, è bene fare sempre una copia di sicurezza che non si sa mai.

Scorrendo il file di configurazione, si arriva all’opzione WP_DEBUG, che di default è impostata su false.

Per attivare il debug, basta cambiare l’opzione da false a true, in questo modo:

define('WP_DEBUG', true);

Dal momento che si attiva il debug di WordPress, tutti gli errori fatali e non, gli avvertimenti e le notifiche di rilievo vengono scritti nelle pagine del sito in cui si manifestano, bacheca compresa, e gli addetti ai lavori possono capire dove andare a mettere le mani per cercare di risolverli.

Opzioni avanzate del debug di WordPress

Il debug di WordPress prevede alcune opzioni, alcune sono utili quando si deve lavorare su un sito in produzione, già pubblicato, altre invece riguardano l’utilizzo avanzato del debug.

Le opzioni vanno aggiunte sempre nel file di configurazione di WordPress, per comodità è meglio scriverle subito dopo l’opzione principale di attivazione vista poco sopra.

L’opzione è la riga che inizia con “define”, la riga precedente è un commento, un promemoria sul suo significato.

1. Scrivere il debug in un file di log

Le stesse informazioni di debug che WordPress scrive nelle pagine possono essere raccolte automaticamente in un file di log, che può tornare molto utile in diversi casi.

Per attivare l scrittura del file di log del debug, aggiungi questa opzione:

// Abilitare la scrittura del file di log del debug /wp-content/debug.log
define('WP_DEBUG_LOG', true);

Di default, WordPress scrive il file di log del debug (debug.log) nella cartella wo-content.

In alternativa, puoi decidere dove e con che nome salvare il file log di debug, utilizzando questa opzione (al posto della precedente)

define ('WP_DEBUG_LOG', '/tmp/errori.log');

Con questa opzione, il file di log errori.log sarà salvato nella cartella “tmp“.

2. Nascondere il debug dalle pagine del sito

La visualizzazione degli errori direttamente sulle pagine del sito può tornare utile in situazioni straordinarie, ma se il sito è pubblicato è brutto mostrare questi errori ai visitatori, meglio nasconderli con l’ istruzione che segue.

Nota bene: va utilizzata assieme alla precedente, altrimenti non avrai più traccia del debug di WordPress e sarà tutto inutile:

// Disabilitare la visualizzazione di errori e notifiche
define('WP_DEBUG_DISPLAY', false);
@ini_set ('display_errors', 0);

Come puoi notare in questo caso le istruzioni da aggiungere sono due, perché a volte quella di WordPress non è abbastanza per non mostrare tutti gli errori, quindi con la seconda viene attivato anche un filtro a livello PHP.

3. Debug di script JS e CSS

Questa opzione risulta molto utile per individuare gli errori degli script JavaScript e CSS, in particolare quando si sta lavorando o modificando questi script.

// Abilitare il debug di script JS e CSS
define('SCRIPT_DEBUG', true);

Va abilitata solo quando è davvero necessaria, perché quando è attiva vengono utilizzati la versione di sviluppo e non compressa degli script, incidendo pesantemente sulle prestazioni del sito.

4. Salvare le query al database

C’è un’ultima opzione possibile, solo per utenti esperti, che consente di salvare il risultato delle query al database in un una variabile.

define('SAVEQUERIES', true);

Questa possibilità va usata solo quando strettamente necessario, perché ha un impatto molto pesante sulle prestazioni di WordPress, anche se è particolarmente utile per capire gli errori riguardanti il database.

Per visualizzare le query la soluzione più comoda è salvarle in un file, diverso dal log di debug.

Per farlo, dopo aver aggiunto l’opzione nel file di configurazione, va aggiunto anche questo snippet al file functions.php:

add_action('shutdown', 'sql_logger');
function sql_logger() {
    global $wpdb;
    $log_file = fopen(ABSPATH.'/sql_log.txt', 'a');
    fwrite($log_file, "//////////////////////////////////////////\n\n" . date("F j, Y, g:i:s a")."\n");
    foreach($wpdb->queries as $q) {
        fwrite($log_file, $q[0] . " - ($q[1] s)" . "\n\n");
    }
    fclose($log_file);
}

Grazie a questo snippet le query vengono salvate nel file sql_log.txt, che troverai nella cartella principale di WordPress.

Non dimenticare attiva questa opzione, altrimenti ti troverai un file di log gigantesco in breve tempo.

Interpretazione delle informazioni di debug

Ora che hai attivato il debug su WordPress, ma è qui che arriva la parte più difficile: interpretare le informazioni su errori e notifiche.

Avere la lista degli errori, ma non sapere cosa significhino, è come non avere nulla.

Tipologie di errori

Potresti trovarti errori di vario tipo, i più gravi sono quelli che iniziano con “fatal error” o “error”.

Poi ci sono i “warning”, avvertimenti che sarebbe il caso di prendere in considerazione, ed i “notice” che invece sono semplici avvisi.

Tra gli avvisi, spesso riguardano funzioni deprecate, cioè temi o plugin (o lo stesso WordPress) che fanno uso di funzioni dismesse o in via di dismissione, che dovrebbero essere sostituite con altre più attuali o corrette, che vengono indicate nella notifica.

Individuare la causa degli errori

Negli errori più gravi è importante risalire alla causa dell’errore, e nel debug viene spesso indicato lo script che lo ha generato.

Grazie al percorso dello script, si può risalire al tema o al plugin che può aver generato il problema.

Alcune indicazioni però sono subdole, magari viene indicato il percorso di uno script, ma la vera causa del problema potrebbe essere un altro script che ha generato un conflitto.

Spesso San Google aiuta a scoprire le cause di questi errori. Talvolta fornisce pure indicazioni su come risolverli, ma il più delle volte occorre una certa dose di dimestichezza con il codice di WordPress, temi e plugin, per venirne a capo.

In ogni caso, avere delle informazioni di debug è già un buon inizio, le puoi fornire ad un tecnico che può risolverti il problema.

Usare solo quando serve

Come hai potuto vedere, il debug di WordPress è un utile strumento di diagnostica, indispensabile nei casi di malfunzionamenti e molto utile anche durante lo sviluppo di un sito, ma va utilizzato solo quando davvero serve, e soprattutto non va scordato attivo.

Appena hai terminato la raccolta di informazioni, e magari risolto il problema, devi ricordarti di disattivare il debug nel file di configurazione di WordPress.

Alcune delle opzioni del debug possono rallentare pesantemente un sito in produzione, ed i file di log possono crescere a dismisura se lasciati attivi, arrivando anche a saturare lo spazio disco disponibile.

Se hai problemi con WordPress, chiedi aiuto ad un professionista

In caso di problemi, il debug di WordPress offre indicazioni utili su come risolverli.

Bisogna però saperli interpretare, non sono alla portata di tutti, e fidarsi senza cognizione di causa di barbatrucchi o indicazioni scovate in rete a volte serve solo a peggiorare la situazione.

In caso di problemi più o meno gravi, o semplici malfunzionamenti che non riesci a risolvere sul tuo sito WordPress o sul tuo store WooCommerce, contattami per un intervento rapido.