Credit : Illustration backtotheweb.fr

Activer le mode debug WordPress : wp-config.php expliqué

Activer le mode debug WordPress : wp-config.php expliqué

Si tu bosses avec WordPress et que tu tombes sur un écran blanc ou un comportement bizarre, la première chose à faire c'est d'activer le mode debug. Je vais t'expliquer chaque constante et te montrer comment les utiliser proprement.

Les constantes essentielles

Ouvre ton fichier wp-config.php à la racine de ton installation WordPress. Tu vas trouver une ligne define('WP_DEBUG', false); — c'est là que tout commence.

WP_DEBUG

define('WP_DEBUG', true);

C'est l'interrupteur principal. Quand tu passes cette valeur à true, WordPress affiche toutes les erreurs PHP, les notices et les warnings. Attention : ne laisse jamais ça activé en production, c'est un risque de sécurité parce que ça peut exposer des chemins de fichiers et des infos sensibles.

WP_DEBUG_LOG

define('WP_DEBUG_LOG', true);

Celui-là, c'est mon préféré. Au lieu d'afficher les erreurs à l'écran, ça les écrit dans un fichier wp-content/debug.log. Sur nos serveurs IONOS, c'est la méthode qu'on recommande systématiquement parce que ça te permet de debugger sans impacter les visiteurs.

Tu peux aussi spécifier un chemin custom :

define('WP_DEBUG_LOG', '/home/htdocs/logs/wp-debug.log');

WP_DEBUG_DISPLAY

define('WP_DEBUG_DISPLAY', false);

Cette constante contrôle si les erreurs s'affichent dans le HTML de la page. En dépannage, on voit souvent des clients qui ont WP_DEBUG à true ET WP_DEBUG_DISPLAY à true en production — résultat, leurs visiteurs voient des messages d'erreur PHP en plein milieu de la page. Pas top.

La bonne pratique c'est : WP_DEBUG_LOG à true et WP_DEBUG_DISPLAY à false.

SAVEQUERIES

define('SAVEQUERIES', true);

Celui-ci est un peu moins connu mais super utile. Il enregistre chaque requête SQL exécutée par WordPress, le temps qu'elle a pris, et la fonction qui l'a appelée. C'est stocké dans le tableau global $wpdb->queries.

Retour d'expérience : j'ai eu un client la semaine dernière avec un site qui mettait 12 secondes à charger. En activant SAVEQUERIES et en installant Query Monitor, on a trouvé un plugin qui faisait 847 requêtes SQL sur la page d'accueil. Le plugin était mal codé et faisait des requêtes dans une boucle sans cache.

Important : SAVEQUERIES consomme de la mémoire. Ne le laisse pas activé plus longtemps que nécessaire.

Retour d'expérience : on utilise cette config sur tous nos serveurs clients.

Configuration complète recommandée pour le debug

Voici le bloc complet que je colle dans le wp-config.php quand je dois investiguer un problème :

// Mode debug — À DÉSACTIVER après investigation
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);
define('SAVEQUERIES', true);
define('SCRIPT_DEBUG', true);

J'ai ajouté SCRIPT_DEBUG qui force WordPress à utiliser les versions non-minifiées des fichiers CSS et JS du core. Pratique si tu suspectes un conflit JavaScript.

Lire le fichier debug.log

Une fois le debug activé, connecte-toi en SSH (ou via le gestionnaire de fichiers IONOS) et regarde le fichier :

tail -f wp-content/debug.log

Le tail -f te permet de suivre les erreurs en temps réel pendant que tu navigues sur le site. C'est la méthode la plus efficace.

Si le fichier est trop gros :

tail -n 200 wp-content/debug.log

Après le debug

N'oublie jamais de remettre tout à false une fois que tu as trouvé le problème :

define('WP_DEBUG', false);

Et supprime le fichier debug.log qui peut contenir des infos sensibles. Sur nos serveurs IONOS, on a déjà vu des fichiers debug.log de plusieurs Go qui bouffaient tout le quota disque du client.

Bon debug !