Debug più leggibile in WordPress: usare WP_DEBUG con Acorn (e Ignition)

In locale, tenere WP_DEBUG attivo non è un vezzo: è l’unico modo realistico per intercettare notice, warning ed eccezioni mentre stai sviluppando temi o plugin. Il problema è che l’esperienza “standard” di WordPress, quando WP_DEBUG (e spesso anche WP_DEBUG_DISPLAY) sono abilitati, è piuttosto spartana: messaggi buttati a schermo, poco contesto, stack trace che non aiutano davvero.

Se lavori con lo stack Roots (in particolare Bedrock + Acorn), puoi rendere il debugging molto più leggibile senza cambiare le abitudini base: lasci WP_DEBUG attivo, ma migliori drasticamente come vengono presentati gli errori.

WP_DEBUG: cosa fa e perché va sempre attivato in sviluppo

WP_DEBUG è la modalità di debug di WordPress: si abilita impostando la costante WP_DEBUG nel file di configurazione. In un ambiente di sviluppo dovrebbe essere sempre attiva per scovare subito problemi che altrimenti resterebbero nascosti (e finirebbero in produzione sotto forma di bug intermittenti).

Se usi Bedrock (il boilerplate moderno per WordPress basato su Composer), la configurazione di sviluppo abilita già WP_DEBUG di default, quindi parti avvantaggiato: non devi ricordarti di accenderlo progetto per progetto.

Il limite dell’output di default di WordPress

Quando WordPress mostra direttamente a schermo errori e avvisi, ottieni sì un segnale immediato, ma spesso con scarsa ergonomia: output mischiato al markup della pagina, informazioni ripetitive e un formato che non guida verso la causa reale. In un ecosistema dove non è raro imbattersi in plugin e temi che generano notice a raffica, questo diventa presto rumore.

Come Acorn migliora WP_DEBUG (Symfony exception handler)

Acorn (il framework application-level dei Roots per portare un’esperienza più “Laravel-like” in WordPress) interviene sull’esperienza di debug quando WP_DEBUG e WP_DEBUG_DISPLAY sono abilitati. In pratica, invece del testo grezzo, Acorn usa di default l’exception handler di Symfony, che rende le eccezioni più leggibili e navigabili.

Ignition su WordPress con Acorn v3: l’esperienza “alla Laravel”

Se arrivi dal mondo Laravel, conosci già Ignition: è la pagina di errore predefinita di Laravel (dalla v9) e offre un contesto molto più utile quando qualcosa va storto. Con l’uscita di Acorn v3, Acorn include il supporto al routing in stile Laravel e questo apre la porta a Ignition anche su siti WordPress basati su Acorn.

Il risultato è una pagina di errore estremamente comoda durante lo sviluppo: stack trace chiari, contesto migliore e una UX di debugging coerente con quella che molti team già usano su progetti Laravel.

Installazione di Ignition (solo dev) via Composer

Per iniziare a usare Ignition in un progetto WordPress con Acorn, installalo come dipendenza di sviluppo con Composer dalla stessa directory dove è installato Acorn:

composer require spatie/laravel-ignition --dev

composer require spatie/laravel-ignition --dev

Chi è rimasto su Acorn v2: whoops come alternativa (ma meglio aggiornare)

Prima di Acorn v3, un abbinamento comune per migliorare l’output era whoops (la libreria PHP per pagine di errore più “umane”). Se sei ancora su Acorn v2, è possibile ottenere un’esperienza migliore rispetto alla pagina Symfony installando whoops. Detto questo, l’indicazione è di valutare l’upgrade ad Acorn v3, dove Ignition diventa un’opzione naturale.

Se non usi Acorn: due plugin utili per il debugging

Non tutti i progetti WordPress nascono (o possono nascere) con Acorn. In quel caso, per migliorare la diagnostica oltre al semplice WP_DEBUG, ci sono plugin che rendono la vita più facile in locale:

• Query Monitor: strumento molto completo per ispezionare query, hook, errori PHP e molto altro; è spesso considerato un “must” in ambienti di sviluppo WordPress.
• Debug Bar: aggiunge un pannello di debug nella toolbar con informazioni utili durante lo sviluppo.

In sintesi: cosa porti a casa

1. In sviluppo, WP_DEBUG dovrebbe essere sempre attivo: riduce i bug “silenziosi”.
2. L’output standard di WordPress è funzionale ma poco leggibile quando gli errori si moltiplicano.
3. Con Acorn, quando WP_DEBUG e WP_DEBUG_DISPLAY sono attivi, ottieni pagine di errore molto più chiare (handler Symfony).
4. Con Acorn v3 puoi usare Ignition (via spatie/laravel-ignition --dev) per un’esperienza di debugging ancora più ricca, in stile Laravel.
5. Senza Acorn, Query Monitor e Debug Bar sono alternative solide per migliorare l’osservabilità in locale.