Dove si trova il debug log di WordPress: la posizione di debug.log e come spostarlo

WordPress scrive il proprio log di debug in wp-content/debug.log per impostazione predefinita — su disco corrisponde a un percorso assoluto tipo /percorso/del/tuo/sito/wp-content/debug.log. Il file non esiste finché non viene registrato davvero qualcosa, e viene scritto solo quando WP_DEBUG è true e WP_DEBUG_LOG è attivo in wp-config.php. Quella posizione predefinita è anche un problema di sicurezza concreto, perché sulla maggior parte degli hosting chiunque può scaricare il file dal browser.

Le tre costanti e cosa fa ciascuna

Vanno tutte e tre in wp-config.php, sopra la riga che dice /* That's all, stop editing! Happy blogging. */. Tutto ciò che aggiungi sotto quella riga viene eseguito dopo l’avvio di WordPress e quindi ignorato.

Costante	Predefinito	Cosa fa
WP_DEBUG	false	Interruttore generale. Alza il livello di segnalazione degli errori PHP per mostrare notice, warning e deprecazioni. Senza di lei niente altro in questo elenco funziona.
WP_DEBUG_LOG	false	Manda gli errori in un file. true significa wp-content/debug.log. Una stringa viene interpretata come il percorso del file su cui scrivere.
WP_DEBUG_DISPLAY	true	Stampa gli errori nell’HTML della pagina, visibili a ogni visitatore.

La dipendenza è la parte che quasi tutti sbagliano. WP_DEBUG_LOG viene letto dentro il ramo WP_DEBUG del codice di avvio di WordPress. Se WP_DEBUG è false, impostare WP_DEBUG_LOG su true non produce assolutamente nulla: nessun file, nessun errore, nessun avviso. Se hai aggiunto WP_DEBUG_LOG e non è comparso alcun log, controlla prima WP_DEBUG.

Una configurazione funzionante per un sito online:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Se WP_DEBUG è già definito più in alto nel file — di solito lo è, impostato su false — modifica quella riga esistente invece di aggiungere un secondo define(). Definire due volte la stessa costante genera un warning PHP che, su un sito con la visualizzazione attiva, finisce dritto in cima alla pagina.

Perché WP_DEBUG_DISPLAY deve essere false in produzione

Con la visualizzazione attiva, gli errori PHP vengono stampati dentro la risposta HTML. Una singola notice di deprecazione di un tema mostra a ogni visitatore il percorso assoluto del filesystem del tuo server. Un errore del database mostra nomi di tabelle e frammenti di query. Peggio ancora, l’output che compare prima dell’invio degli header rompe i redirect, rompe le risposte REST e AJAX che si aspettano JSON pulito e può produrre quella schermata bianca di cui poi si dà la colpa a un plugin.

Una sottigliezza da conoscere: impostare WP_DEBUG_DISPLAY su null non è la stessa cosa di false. null dice a WordPress di non toccare l’impostazione display_errors di PHP e di ereditare quella configurata sul server. false la forza attivamente a spento. Su un sito in produzione usa false e aggiungi la riga ini_set vista sopra come misura di sicurezza aggiuntiva, dato che un plugin può riattivare display_errors più avanti nella richiesta.

La posizione predefinita è scaricabile pubblicamente

wp-content/debug.log si trova dentro la web root. In un’installazione WordPress standard non c’è nulla che blocchi le richieste dirette a quel file. Su una tipica configurazione Apache o nginx, https://tuosito.com/wp-content/debug.log restituisce il file come testo semplice. I log di debug contengono percorsi assoluti del server, dettagli interni di plugin e temi, errori del database con il testo reale delle query e a volte valori passati a funzioni che stavano fallendo. È materiale di ricognizione gratuito per chiunque indovini l’URL — ed è uno dei primi URL che gli scanner automatici provano.

Ci sono due modi per affrontarlo. Il migliore è spostare il log.

Spostare il log indicando un percorso

Da WordPress 5.1, WP_DEBUG_LOG accetta una stringa con il percorso del file al posto di un booleano. Puntalo da qualche parte fuori dalla document root:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/home/youruser/logs/wp-errors.log' );
define( 'WP_DEBUG_DISPLAY', false );

Tre regole per quel percorso. Usa un percorso assoluto — uno relativo viene risolto rispetto alla directory di lavoro di PHP, che cambia da richiesta a richiesta e da server a server, quindi perderesti le tracce del file. La directory deve già esistere: PHP non la crea, e se non riesce ad aprire il file fallisce in silenzio. E la directory deve essere scrivibile dall’utente PHP, che su hosting condiviso non è lo stesso account con cui accedi via SFTP.

Se il tuo hosting ti confina dentro la web root e non c’è nessun posto più in alto dove scrivere, tieni il percorso predefinito e blocca l’accesso a livello di server. Su Apache:

<Files "debug.log">
  Require all denied
</Files>

Va messo in un file .htaccess dentro wp-content, non in quello nella root: WordPress riscrive l’.htaccess della root quando salvi i permalink e può cancellare la tua aggiunta. Su nginx l’.htaccess non fa proprio nulla; serve un blocco location nella configurazione del server, cosa che sull’hosting gestito significa di solito scrivere all’assistenza.

Sii onesto su cosa ti dà davvero il blocco: il file resta su disco, in una directory servita dal web server. Un bug di path traversal in un qualsiasi plugin può comunque leggerlo. Spostarlo fuori dalla web root è la soluzione più solida.

Leggere e seguire il file

Via SSH, guardalo in tempo reale mentre riproduci il bug:

tail -f wp-content/debug.log

Riproduci l’errore in un’altra scheda e le nuove righe compaiono mentre vengono scritte. Per vedere solo ciò che è successo di recente, o per filtrare su un singolo plugin:

tail -n 100 wp-content/debug.log
grep -i 'plugin-slug' wp-content/debug.log | tail -n 50

PHP aggiunge in fondo al file, quindi leggi dal basso verso l’alto. Ogni voce ha un orario in UTC, che non corrisponderà al fuso orario impostato in WordPress: non farti ingannare pensando di star guardando voci vecchie.

Con WP-CLI puoi modificare le costanti senza mettere mano al file:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Il flag --raw è importante: senza, il valore viene scritto come stringa "true" invece che come booleano. Per la forma con il percorso, togli --raw così viene scritto come stringa fra virgolette.

Niente SSH? Scarica il file via SFTP o aprilo dal file manager dell’hosting. Evita i plugin che mostrano il log dentro wp-admin, a meno che tu non ti fidi ciecamente: stai dando a un plugin accesso in lettura a un file pieno di dettagli interni del server.

Se vuoi il blocco esatto da mettere in wp-config per la tua configurazione, percorso sicuro fuori dalla root e regola server abbinata comprese, il generatore di debug log per WordPress te lo costruisce.

Spegnilo quando hai finito

Nel core di WordPress non c’è nulla che ruoti o svuoti debug.log. Su un sito che genera una notice a ogni caricamento di pagina, il file cresce senza limite e può riempire il disco, mandando giù il sito molto più duramente del bug che stavi inseguendo. Attiva il logging, riproduci il problema, leggi il log e poi rimetti WP_DEBUG su false.

Per svuotare il file senza eliminarlo:

: > wp-content/debug.log

Quando il log resta vuoto

Procedi in quest’ordine. WP_DEBUG è false — la causa in assoluto più comune, e disattiva silenziosamente tutto il resto. La costante è sotto la riga “stop editing” in wp-config.php. Permessi dei file — PHP non riesce a scrivere in wp-content, o nella directory personalizzata che hai indicato. Un errore fatale prima che wp-config finisca di caricarsi, per esempio un errore di sintassi nel file di configurazione stesso, avviene troppo presto perché il logging di WordPress lo intercetti: quegli errori finiscono nel log degli errori PHP del server. Il tuo hosting sovrascrive le impostazioni — alcune piattaforme gestite fissano l’impostazione error_log di PHP o dirottano i log nella loro dashboard, e in quel caso le tue costanti sono corrette ma l’output è semplicemente altrove. Controlla il visualizzatore di log dell’hosting prima di dare per scontato che la tua configurazione sia sbagliata.