Activer le mode debug WordPress : guide sécurisé

Pour activer le mode debug WordPress, ouvrez le fichier wp-config.php, placez les constantes de diagnostic avant la ligne « That’s all, stop editing » et activez surtout le journal avec WP_DEBUG_LOG et l’affichage désactivé avec WP_DEBUG_DISPLAY. Reproduisez ensuite l’erreur, lisez wp-content/debug.log, corrigez la cause, puis remettez WP_DEBUG à false en production. Cette méthode révèle les erreurs PHP sans les montrer aux visiteurs.

Le mode debug WordPress est le dispositif natif qui enregistre les avertissements, notices et erreurs PHP produits par le cœur, le thème ou les extensions. Il ne répare rien automatiquement. Son rôle est de transformer un symptôme vague, comme une page blanche ou une erreur 500, en indice exploitable.

Quand activer le mode debug WordPress

Activez le diagnostic juste avant de reproduire un problème précis : écran blanc dans l’administration, bloc qui ne s’enregistre pas, erreur après une mise à jour, formulaire qui ne répond plus ou ralentissement lié à une extension. Notez l’heure, l’URL, l’action effectuée et le compte utilisé. Cette chronologie facilite la recherche dans le journal.

Évitez de laisser le debug public actif. Avec WP_DEBUG_DISPLAY à true, une trace peut exposer un chemin serveur, un nom de table, une version de bibliothèque ou une partie de requête. Même un avertissement sans gravité devient une fuite d’information quand il est envoyé à chaque visiteur.

Le debug est particulièrement utile après une modification de thème. Il permet de distinguer une erreur de syntaxe PHP, une fonction dépréciée, un appel à une variable inexistante et un conflit d’extension. Il faut cependant comparer les nouvelles lignes avec le journal antérieur, car un site ancien peut déjà contenir des avertissements sans rapport avec la panne actuelle.

# Exemple de sauvegarde avant modification
cp wp-config.php wp-config.php.bak-debug

# Vérifier la présence des constantes
grep -n 'WP_DEBUG' wp-config.php

Configurer wp-config.php sans afficher les erreurs

Les constantes doivent être placées dans wp-config.php, avant le commentaire de fin qui indique de ne plus modifier le fichier. Si une constante existe déjà, modifiez sa valeur au lieu de créer une seconde définition. Une duplication rend le diagnostic confus, car PHP conserve la première constante déjà définie.

Le réglage recommandé en production temporaire active le journal, désactive l’affichage et empêche les erreurs d’être envoyées dans le HTML. Le fichier de log doit rester inaccessible depuis le navigateur. Sur un serveur Apache ou Nginx correctement configuré, le dossier wp-content ne doit pas permettre de télécharger debug.log.

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

Le préfixe @ devant ini_set ne remplace pas la configuration du serveur, mais évite qu’un avertissement secondaire soit affiché pendant le diagnostic. N’ajoutez pas de code trouvé au hasard dans functions.php. Le point de configuration central est plus facile à retirer et limite le risque de casser le thème.

Lire debug.log et isoler la vraie cause

Après avoir enregistré le fichier, reproduisez une seule fois le problème. Ouvrez ensuite wp-content/debug.log et commencez par les dernières lignes. Cherchez le nom d’un plugin, d’un thème, d’un fichier PHP et le numéro de ligne. Une trace avec Fatal error est généralement prioritaire sur une longue série de notices.

Classez chaque message. Une erreur fatale arrête l’exécution. Une erreur de syntaxe empêche souvent le chargement du fichier entier. Un avertissement signale une situation risquée mais ne bloque pas toujours la page. Une fonction dépréciée indique une compatibilité à corriger, mais elle n’explique pas forcément une panne immédiate.

Ne supprimez pas les lignes du journal avant de les copier dans un fichier local sécurisé. Conservez l’heure et le contexte, sans publier les chemins absolus, les adresses internes ou les données personnelles. Si le fichier devient énorme, archivez-le après avoir corrigé la cause et surveillez sa croissance.

# Lire les dernières lignes sur Linux
tail -n 80 wp-content/debug.log

# Suivre le journal pendant une reproduction
tail -f wp-content/debug.log

# Rechercher les erreurs fatales
grep -nE 'Fatal error|Parse error|Uncaught' wp-content/debug.log

Différencier erreur PHP, extension et thème

Le nom du fichier dans la trace donne le premier axe d’enquête. Un chemin sous wp-content/plugins pointe souvent vers une extension. Un chemin sous wp-content/themes oriente vers le thème actif ou un composant enfant. Un chemin sous wp-includes ne signifie pas automatiquement que WordPress est fautif : une extension peut avoir appelé le cœur avec des données invalides.

Pour isoler un conflit, désactivez temporairement l’extension suspecte et reproduisez l’action. Si l’administration est inaccessible, WP CLI permet de couper une extension depuis le terminal. Sur un site critique, faites ce test pendant une fenêtre de maintenance et sauvegardez avant toute manipulation.

Le thème peut être isolé en activant temporairement un thème officiel installé. Si la panne disparaît, comparez les hooks récemment modifiés, les fichiers inclus et les fonctions déclarées. Une erreur sur un hook exécuté partout peut casser la page d’accueil, l’administration et les appels AJAX en même temps.

# Voir les extensions actives
wp plugin list --status=active

# Désactiver l’extension identifiée
wp plugin deactivate nom-extension

# Réactiver après le test
wp plugin activate nom-extension

Utiliser WP DEBUG LOG avec WP CLI

WP CLI facilite le diagnostic quand le navigateur masque l’erreur ou quand LiteSpeed sert une réponse en cache. Commencez par vérifier la syntaxe PHP et la configuration WordPress. Les commandes doivent être lancées avec l’utilisateur du site, pas systématiquement avec les privilèges root.

La commande wp core verify-checksums peut détecter un fichier du cœur modifié, à condition que la version et la langue soient disponibles dans les sommes de contrôle. Pour les extensions, utilisez leurs mises à jour officielles et comparez les fichiers seulement dans un environnement de test.

Un journal vide ne prouve pas que le code fonctionne. Il peut être écrit dans un chemin différent, bloqué par les permissions ou nettoyé par une rotation. Vérifiez la date de modification du fichier et les droits du dossier. Si vous utilisez un hébergement mutualisé, le support peut indiquer le chemin PHP réellement utilisé.

# Contrôles WP CLI
wp core version
wp core verify-checksums
wp option get blogname

# Vérifier les droits sans les élargir inutilement
ls -l wp-config.php wp-content/debug.log

Sécuriser le fichier de journal et les permissions

Un fichier de log peut contenir des chemins, des paramètres de requête et parfois des fragments de données envoyées par un visiteur. Ne le laissez pas accessible par une URL publique. Vérifiez avec une requête HTTP que /wp-content/debug.log renvoie une réponse interdite ou inexistante, jamais son contenu.

Les permissions doivent permettre au processus PHP d’écrire le journal, mais pas autoriser toute personne à le modifier. Le réglage exact dépend de l’utilisateur PHP, du groupe et de la configuration de l’hébergement. Ne passez pas le dossier en écriture universelle pour résoudre un problème de permissions.

Après l’analyse, téléchargez le journal par un canal administrateur, supprimez les données sensibles, puis effacez ou archivez le fichier. Si le serveur utilise une rotation de logs, définissez une limite de taille. Un debug oublié peut remplir le disque et provoquer une panne qui n’a plus rien à voir avec l’erreur initiale.

# Exemple de contrôle HTTP, à adapter à votre domaine
curl -I https://exemple.fr/wp-content/debug.log

# Nettoyer le journal après sauvegarde sécurisée
: > wp-content/debug.log

Résoudre les erreurs fréquentes révélées par le debug

Une erreur Call to undefined function indique souvent une extension absente, un chargement conditionnel incorrect ou une incompatibilité de version PHP. Une erreur Cannot redeclare signale généralement un fichier inclus deux fois ou une fonction déclarée sans garde. Une erreur Allowed memory size exhausted demande une analyse de la mémoire PHP, pas seulement une désactivation du debug.

Une erreur de syntaxe après une édition vient souvent d’une accolade manquante, d’une virgule oubliée ou d’une chaîne non fermée. Contrôlez le fichier avec php -l avant de le remettre en ligne. Ne corrigez pas directement un plugin tiers si une mise à jour officielle existe, sinon la modification sera écrasée.

Les notices sur les fonctions dépréciées doivent être traitées comme une dette de compatibilité. Mettez à jour le thème et les extensions sur une copie de test, puis vérifiez les pages importantes. L’objectif est de supprimer la cause, pas de masquer tous les messages avec un réglage plus permissif.

# Vérifier la syntaxe d’un fichier avant déploiement
php -l wp-content/themes/mon-theme/functions.php

# Chercher les fonctions dépréciées dans le journal
grep -nEi 'deprecated|notice|warning' wp-content/debug.log | tail -40

Désactiver le debug après le diagnostic

Une fois le problème corrigé et vérifié, remettez WP_DEBUG à false. Vous pouvez conserver WP_DEBUG_LOG uniquement si une surveillance maîtrisée l’exige, mais le journal doit alors être protégé, limité et régulièrement contrôlé. Pour la plupart des sites, le debug temporaire est préférable.

Testez la page publique, la connexion à l’administration, l’enregistrement d’un brouillon, un formulaire et les appels AJAX concernés. Purgez ensuite le cache de page si l’hébergement en utilise un. Une ancienne réponse en cache peut donner l’impression que l’erreur est toujours présente ou qu’elle a disparu.

Si la panne est une erreur 500, consultez le guide de diagnostic d’une erreur 500 WordPress. Pour un problème de connexion à l’administration, le guide de connexion à wp-admin aide à distinguer cookies, identifiants et erreur serveur. Si le site est lent, comparez aussi les traces avec le guide du back office WordPress lent.

# Configuration finale de production
define( 'WP_DEBUG', false );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

FAQ sur le mode debug WordPress

Comment activer le mode debug WordPress sans afficher les erreurs ?

Ajoutez WP_DEBUG et WP_DEBUG_LOG à true, puis laissez WP_DEBUG_DISPLAY à false dans wp-config.php. Les traces seront écrites dans wp-content/debug.log au lieu d’être montrées aux visiteurs.

Où se trouve le fichier debug.log de WordPress ?

Avec la configuration standard, le fichier se trouve dans wp-content/debug.log. Un filtre ou une constante personnalisée peut changer son emplacement. Contrôlez sa date de modification après une reproduction et vérifiez que ses permissions ne permettent pas une lecture publique.

Faut-il laisser WP_DEBUG activé en production ?

Non, sauf dispositif de supervision correctement sécurisé. L’affichage des erreurs peut divulguer des informations techniques et un journal volumineux peut remplir le disque. Activez le debug pour diagnostiquer, corrigez la cause, puis désactivez-le.

Comment activer le debug WordPress si wp-admin est inaccessible ?

Modifiez wp-config.php avec le gestionnaire de fichiers, SFTP ou SSH, puis consultez wp-content/debug.log. Si vous avez WP CLI, désactivez aussi l’extension indiquée dans la trace et reproduisez l’erreur en terminal.

Le mode debug ralentit-il WordPress ?

Il peut augmenter les écritures disque et ralentir un site qui génère beaucoup de notices, surtout avec un trafic élevé. Utilisez-le brièvement, surveillez la taille du journal et désactivez-le après le test.

Sources utiles : documentation WordPress sur le débogage, référence des constantes de debug WordPress, WP CLI pour vérifier les fichiers du cœur, documentation PHP sur la vérification de syntaxe, documentation Apache sur htaccess, guide WordPress de durcissement.