WP_DEBUG, mais en mieux : déboguer WordPress proprement avec Acorn (Symfony, Ignition, Whoops)

Sur un projet WordPress, activer WP_DEBUG en développement est non négociable : tu repères plus tôt les notices PHP, les erreurs fatales, les appels dépréciés, et tu évites d’empiler des “petits soucis” qui explosent plus tard en prod. Le problème, c’est que l’affichage par défaut de WordPress est… minimaliste : un message en clair injecté dans la page, souvent sans contexte exploitable.

Si tu travailles avec Acorn (le runtime PHP de Roots qui apporte une couche “Laravel-like” à WordPress), tu peux considérablement améliorer cette expérience : pages d’exception plus propres, stack traces plus lisibles, et possibilité d’utiliser Ignition (la page d’erreur moderne bien connue côté Laravel).

Rappel : ce que fait vraiment WP_DEBUG (et pourquoi ça ne suffit pas)

WP_DEBUG est le mode debug natif de WordPress. Une fois activé, WordPress et PHP te remontent plus facilement les warnings/notices/erreurs, ce qui est essentiel quand tu développes un thème, un plugin, ou même une intégration “simple”.

Mais l’output par défaut a deux défauts majeurs :

• Lisibilité limitée : message brut au milieu du HTML, sans mise en forme ni hiérarchie.
• Contexte pauvre : selon les cas, la trace est incomplète ou peu exploitable, surtout quand plusieurs couches (plugins, MU-plugins, thème) s’empilent.

Avec Bedrock, WP_DEBUG est déjà dans les bons rails

Si tu utilises Bedrock (le boilerplate WordPress moderne de Roots basé sur Composer), tu pars déjà avec une configuration d’environnements plus propre. D’après la documentation Roots, WP_DEBUG est activé par défaut en environnement de développement dans Bedrock, ce qui évite l’oubli classique du “j’ai débogué sans debug”.

Acorn : améliorer l’affichage des erreurs quand WP_DEBUG est activé

Acorn améliore l’output d’erreur lorsque WP_DEBUG est activé et que l’affichage est autorisé côté WordPress (typiquement via WP_DEBUG_DISPLAY). Concrètement, au lieu d’un message brut, tu obtiens une page d’exception structurée.

1) Par défaut : le handler d’exceptions Symfony

Sans rien installer de plus, Acorn s’appuie sur le gestionnaire d’exceptions Symfony pour rendre les erreurs plus lisibles. Tu as une mise en forme claire, une trace plus exploitable et, globalement, une expérience plus proche de ce qu’on attend d’un projet PHP moderne.

2) Le confort maximal : Ignition (l’erreur page “Laravel”)

Si tu viens de Laravel, Ignition te parlera tout de suite : c’est la page d’erreur par défaut de Laravel depuis la v9. La nouveauté côté Roots, c’est qu’avec Acorn v3, le support du routing “façon Laravel” implique aussi la compatibilité avec Ignition sur WordPress.

Le résultat : une page d’erreur très riche, des stack traces bien présentées, et une ergonomie nettement supérieure quand tu dois comprendre vite pourquoi une requête part en erreur.

Pour l’installer (en dépendance de dev), Roots recommande simplement d’exécuter la commande Composer suivante depuis le dossier où Acorn est installé :

composer require spatie/laravel-ignition --dev

composer require spatie/laravel-ignition --dev

3) Whoops : l’alternative historique (surtout si tu es encore sur Acorn v2)

Avant Acorn v3, le duo classique pour améliorer la page d’erreur, c’était Acorn + Whoops (la librairie PHP d’erreurs “joliment affichées” très utilisée). Si tu es encore sur Acorn v2, Roots indique qu’il reste possible d’améliorer l’expérience en installant Whoops, même si la recommandation principale est plutôt de passer sur Acorn v3.

Et si tu n’utilises pas Acorn ? Deux options WordPress très utiles

Tout le monde n’a pas Acorn sur ses projets (même si, objectivement, profiter d’outils et d’habitudes “framework” en PHP peut faire du bien). Si ton stack reste 100% WordPress classique, tu peux quand même muscler ton debug avec des plugins dédiés.

• Query Monitor : généralement incontournable en local (requêtes, hooks, erreurs, timings…).
• Debug Bar : une barre de debug simple à activer, pratique pour inspecter rapidement l’exécution.

Synthèse : la combinaison la plus efficace en dev

Pour une expérience de débogage WordPress vraiment confortable : active WP_DEBUG en environnement de dev, et, si ton projet s’y prête, utilise Acorn pour profiter d’un rendu d’exceptions moderne. Avec Acorn v3 + Ignition, tu te rapproches d’une DX comparable à Laravel tout en restant sur WordPress — ce qui change radicalement la vitesse à laquelle tu identifies (et corriges) les erreurs.