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

Credit : Logo officiel

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

Dylan D. — Agent Support Technique Serveur WordPress 1880 mots 10 min de lecture

Activer le mode debug WordPress : wp-config.php explique

Vendredi 17h, un client m'appelle en panique. Son site WooCommerce sous WordPress 6.5 affiche une page blanche depuis qu'il a mis a jour un plugin de paiement. Aucun message d'erreur, juste du blanc. Le back-office repond plus non plus. Premiere reaction du client : il a appele son developpeur (en vacances), puis cherche un autre prestataire. Moi, en deux minutes via SSH, j'active le mode debug WordPress et je vois le coupable : un fatal error PHP 8.3 sur une fonction depreciee dans le plugin. Probleme identifie, plugin desactive via WP-CLI, site en ligne. Cinq minutes chrono.

Le mode debug, c'est l'outil le plus puissant et le plus mal compris de WordPress. La plupart des tutos te disent juste "mets WP_DEBUG a true" et basta. Sauf que mal configure, ca peut exposer des donnees sensibles a tes visiteurs ou pourrir tes performances. Je t'explique chaque constante en detail, comment les combiner, et comment lire les logs sans paniquer.

Les constantes essentielles de wp-config.php

Ouvre ton wp-config.php a la racine de ton WordPress. Cherche la ligne define('WP_DEBUG', false); -- c'est le point de depart. Ce fichier contient toute la configuration de ton WordPress : connexion BDD, cles de salage, et toutes les constantes de debug. Edite-le toujours via SSH ou FTP, jamais via un plugin (parce que si ton site est casse, ton plugin l'est aussi).

WP_DEBUG : l'interrupteur principal

define('WP_DEBUG', true);

C'est la constante mere. Active a true, elle declenche l'affichage de toutes les erreurs PHP : notices, warnings, deprecated, fatal errors. Sans elle, WordPress masque les erreurs et tu vois juste une page blanche en cas de probleme.

Attention critique : ne laisse jamais WP_DEBUG a true en production sans WP_DEBUG_DISPLAY a false. Sinon tes visiteurs voient des messages comme :

Warning: Undefined array key "user_id" in /home/htdocs/wp-content/plugins/woocommerce/includes/class-wc-cart.php on line 234

Ca expose les chemins absolus de ton serveur, la structure de tes plugins, parfois meme des bouts de requetes SQL. C'est une mine d'or pour un attaquant.

WP_DEBUG_LOG : ecrire dans un fichier

define('WP_DEBUG_LOG', true);

Ma constante preferee, et de loin. Au lieu d'afficher les erreurs a l'ecran, elle les ecrit dans wp-content/debug.log. Sur les serveurs IONOS, c'est la methode qu'on recommande systematiquement parce qu'elle te permet de debugger sans impacter l'experience visiteur.

Depuis WordPress 5.1, tu peux specifier un chemin custom pour eviter que le fichier soit accessible publiquement :

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

Je place toujours le log en dehors de la racine web. Sinon, n'importe qui peut faire https://monsite.fr/wp-content/debug.log et lire toutes tes erreurs avec leurs chemins absolus. Si tu peux pas placer le fichier hors webroot (cas typique du mutualise), protege-le avec un .htaccess :

<Files "debug.log">
  Order allow,deny
  Deny from all
</Files>

WP_DEBUG_DISPLAY : controler l'affichage

define('WP_DEBUG_DISPLAY', false);

Cette constante controle si les erreurs PHP s'affichent dans le HTML envoye au navigateur. En production, elle doit toujours etre a false. En depannage, on voit souvent des clients qui ont WP_DEBUG a true ET WP_DEBUG_DISPLAY a true en production. Resultat : les visiteurs voient des messages d'erreur PHP en plein milieu de la page d'accueil. Pas top pour la conversion.

La combinaison gagnante c'est : WP_DEBUG_LOG a true et WP_DEBUG_DISPLAY a false. Tu loggues sans afficher.

SAVEQUERIES : tracer les requetes SQL

define('SAVEQUERIES', true);

Moins connue mais redoutable. Cette constante enregistre dans la variable globale $wpdb->queries chaque requete SQL executee, avec son temps d'execution et la fonction qui l'a appelee. Combinee au plugin Query Monitor, c'est l'outil ultime pour traquer les sites lents.

La semaine derniere, un client avec un site qui mettait 12 secondes a charger. Activation de SAVEQUERIES + Query Monitor : on a trouve un plugin de cross-selling qui faisait 847 requetes SQL sur la page d'accueil. Huit cent quarante-sept. Le plugin etait mal code et requetait dans une boucle sans cache. Plugin vire, page a 1.4 secondes.

Attention : SAVEQUERIES consomme pas mal de memoire RAM. Sur un site avec beaucoup de trafic, ne l'active jamais en continu. C'est un outil de diagnostic ponctuel.

SCRIPT_DEBUG : versions non-minifiees

define('SCRIPT_DEBUG', true);

Cette constante force WordPress a charger les versions non-minifiees des fichiers CSS et JS du core. Indispensable quand tu suspectes un conflit JavaScript ou que tu veux lire la stack trace d'une erreur dans la console navigateur. Sans ca, tu vois wp-includes/js/jquery/jquery.min.js:2:15847 -- bonne chance pour debugger.

La configuration complete que j'utilise

Voila le bloc que je colle dans wp-config.php quand je dois investiguer un probleme sur WordPress 6.x :

// Mode debug -- A DESACTIVER apres investigation
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', '/home/htdocs/logs/wp-debug.log');
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);
define('SAVEQUERIES', true);
define('SCRIPT_DEBUG', true);

// Augmenter la memoire pour eviter les fatal pendant le debug
define('WP_MEMORY_LIMIT', '512M');

La ligne @ini_set('display_errors', 0); est importante : elle force PHP a pas afficher les erreurs meme si la config serveur dit l'inverse. Ceinture et bretelles.

Lire et exploiter le fichier debug.log

tail -f /home/htdocs/logs/wp-debug.log

Le tail -f te permet de suivre les erreurs en temps reel pendant que tu navigues sur le site. C'est la methode la plus efficace, clairement. Ouvre un terminal SSH avec le tail, charge la page qui pose probleme dans un autre onglet, et tu vois les erreurs apparaitre direct.

Si le fichier est deja enorme, regarde juste les 200 dernieres lignes :

tail -n 200 /home/htdocs/logs/wp-debug.log

Pour filtrer uniquement les fatal errors :

grep "PHP Fatal" /home/htdocs/logs/wp-debug.log

Pour voir les erreurs d'un plugin specifique :

grep "woocommerce" /home/htdocs/logs/wp-debug.log | tail -50

Comprendre une ligne de log

Une entree typique ressemble a ca :

[07-May-2026 14:23:11 UTC] PHP Warning: Undefined array key "customer_id" in /home/htdocs/wp-content/plugins/woocommerce/includes/class-wc-order.php on line 1245

Tu as le timestamp, le niveau (Warning, Notice, Fatal), le message, le fichier et la ligne. Quand tu vois une erreur fatale, c'est le fichier qui plante ton site. Les warnings et notices sont moins critiques mais a corriger quand meme parce que ca peut casser sur PHP 8.4 (qui transforme certains warnings en errors).

Debugger sans toucher au wp-config.php

Parfois tu veux activer le debug juste sur un environnement (staging) sans modifier le wp-config.php. WordPress 5.5+ supporte des fichiers de config par environnement.

Cree wp-config-staging.php :

<?php
define('WP_ENVIRONMENT_TYPE', 'staging');
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Dans wp-config.php, ajoute :

if (defined('WP_ENVIRONMENT_TYPE') && WP_ENVIRONMENT_TYPE === 'staging') {
    require_once __DIR__ . '/wp-config-staging.php';
}

Propre, separe la prod du staging.

Query Monitor : le compagnon indispensable

Le mode debug native de WordPress est puissant mais brut. Pour aller plus loin, installe Query Monitor, le plugin de debug le plus populaire :

wp plugin install query-monitor --activate

Une fois active, Query Monitor ajoute une barre admin avec :

C'est une version visuelle de SAVEQUERIES + bien plus. Pour les visiteurs non-connectes, Query Monitor ne s'affiche pas. Pour les admins, il est en bas de page.

Une combinaison gagnante : WP_DEBUG_LOG pour les erreurs en background + Query Monitor pour les analyses live. La 99% des bugs WordPress se diagnostiquent avec ces deux outils en moins de 15 minutes.

Debugger les hooks WordPress

Quand un plugin agit pas comme prevu, c'est souvent un probleme de hook qui est attache au mauvais moment ou dans le mauvais ordre. Pour tracer tous les hooks declenches sur une page :

add_action('all', function($hook) {
    if (current_user_can('administrator')) {
        error_log('Hook fired: ' . $hook);
    }
});

A mettre temporairement dans functions.php du theme actif. Ca log absolument tous les hooks dans wp-debug.log. Tres verbeux mais utile pour comprendre l'ordre d'execution.

Pour voir uniquement les actions attachees a un hook specifique :

global $wp_filter;
var_dump($wp_filter['init']);

Attention, c'est massif comme sortie. A utiliser avec moderation.

Erreurs courantes et leur fix

Le fichier debug.log n'est pas cree

Verifie que le repertoire est accessible en ecriture par le user PHP :

ls -la /home/htdocs/wp-content/
chmod 755 /home/htdocs/wp-content/
touch /home/htdocs/wp-content/debug.log
chmod 644 /home/htdocs/wp-content/debug.log

Sur les hebergements mutualises IONOS, utilise chmod 705 pour les dossiers et 604 pour les fichiers (le user web et ton user FTP sont differents).

debug.log fait plusieurs gigas

Classique. Sur un site avec beaucoup de warnings, le fichier grossit a vue d'oeil. Met en place une rotation :

# /etc/logrotate.d/wordpress-debug
/home/htdocs/logs/wp-debug.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    create 644
}

Ou purge manuellement :

> /home/htdocs/logs/wp-debug.log

Page blanche meme avec WP_DEBUG

Si tu vois toujours du blanc, c'est que l'erreur survient avant le chargement de wp-config. Active le debug PHP global dans un .user.ini a la racine :

display_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /home/htdocs/logs/php-errors.log

Les erreurs s'affichent quand meme

Meme avec WP_DEBUG_DISPLAY = false, certaines erreurs apparaissent. C'est que PHP ignore la config WordPress. Force avec :

ini_set('display_errors', '0');
error_reporting(0);

A mettre tout en haut du wp-config.php.

Les requetes SQL s'enregistrent pas

Pour utiliser SAVEQUERIES, faut que les requetes passent par $wpdb. Si un plugin utilise PDO directement ou mysqli, elles seront pas tracees. Query Monitor est plus exhaustif que SAVEQUERIES seul.

Apres le debug, on remet tout propre

Une fois ton probleme identifie et corrige, n'oublie jamais de tout desactiver :

define('WP_DEBUG', false);
define('WP_DEBUG_LOG', false);
define('SAVEQUERIES', false);
define('SCRIPT_DEBUG', false);

Et supprime le fichier debug.log :

rm /home/htdocs/logs/wp-debug.log

Le debug.log peut contenir des hashes de mots de passe partiels, des adresses email, des cles d'API exposees dans des erreurs. C'est sensible. Sur IONOS, on a deja vu des fichiers debug.log de plusieurs Go qui bouffaient tout le quota disque du client et lui faisaient depasser son forfait.

Pour aller plus loin

Le debug WordPress n'est qu'une brique de l'arsenal. Voici les ressources complementaires que je conseille :

Le debug, une discipline pas un reflexe

Le mode debug WordPress c'est pas un bouton magique qui repare ton site. C'est un projecteur qui eclaire ce qui ne va pas. Le vrai travail commence apres : lire les logs, comprendre les stack traces, isoler le coupable. Avec le temps, tu developpes un instinct -- tu vois "Call to undefined function" et tu sais immediatement qu'un plugin est desactive ou qu'un fichier manque. Tu vois "Allowed memory size exhausted" et tu sais qu'il faut augmenter WP_MEMORY_LIMIT ou trouver la fuite memoire.

Garde toujours un wp-config.php propre en production, debug strictement local ou en staging, et logs hors webroot. Ces trois regles t'eviteront 95% des galeres. Et le jour ou un client t'appelle en panique a 17h un vendredi, tu sauras quoi faire en deux minutes.

# Articles similaires

Sur les memes sujets et plus loin