Comment activer et utiliser WP_DEBUG sur WordPress ?

PerformanceSécuritéMaintenanceComment activer et utiliser WP_DEBUG sur WordPress ?

Pour activer le mode debug de WordPress, ajoutez define('WP_DEBUG', true); dans votre fichier wp-config.php. Cela permet d’afficher les erreurs PHP, les avertissements et les notices, essentiels pour identifier et corriger les dysfonctionnements de votre site. Contrairement à de nombreux guides, nous détaillerons aussi comment utiliser WP_DEBUG_LOG pour enregistrer ces erreurs discrètement, sans les afficher aux visiteurs, une pratique bien plus sûre et professionnelle.

🎯

Qu’est-ce que WP_DEBUG et pourquoi est-il crucial pour votre site WordPress ?

WP_DEBUG est une constante PHP intégrée à WordPress qui permet d’activer le mode de débogage. Concrètement, lorsque vous l’activez, votre site WordPress commence à afficher ou à enregistrer toutes les erreurs, avertissements (warnings) et notifications (notices) PHP qui se produisent. Ces messages sont souvent invisibles par défaut, car WordPress est configuré pour masquer les erreurs aux visiteurs afin d’offrir une meilleure expérience utilisateur et d’éviter de révéler des informations potentiellement sensibles.

Mais pour un développeur ou un administrateur de site, ces messages sont une mine d’or. Ils indiquent précisément où et pourquoi un problème survient : un plugin en conflit, un thème mal codé, une mise à jour qui a échoué, ou même une configuration serveur incorrecte. Sans WP_DEBUG, vous seriez à tâtons face à un écran blanc (la fameuse « White Screen of Death ») ou à un comportement inattendu de votre site.

Ignorer les erreurs PHP, c’est comme conduire une voiture avec un voyant moteur allumé : ça fonctionne, jusqu’au jour où ça ne fonctionne plus du tout. WP_DEBUG est votre diagnostic embarqué.

Nicolas Buathier, Expert WordPress

🛠️

Comment activer le mode debug sur WordPress (WP_DEBUG) ?

L’activation de WP_DEBUG se fait en modifiant le fichier wp-config.php, qui est l’un des fichiers les plus importants de votre installation WordPress. Avant toute modification, assurez-vous de faire une sauvegarde de ce fichier et, idéalement, de l’ensemble de votre site. Une erreur dans wp-config.php peut rendre votre site inaccessible.

1️⃣

Étape 1 : Accédez à votre fichier wp-config.php

Connectez-vous à votre serveur via FTP ou le gestionnaire de fichiers. Naviguez jusqu’au répertoire principal de votre site WordPress (souvent public_html ou www). Téléchargez une copie de wp-config.php sur votre ordinateur ou ouvrez-le directement via l’éditeur de votre hébergeur.

2️⃣

Étape 2 : Localisez la ligne d’activation

Recherchez la ligne suivante dans le fichier :

define('WP_DEBUG', false);

Cette ligne est présente par défaut dans la plupart des installations WordPress. Si elle n’existe pas, vous devrez l’ajouter.

3️⃣

Étape 3 : Modifiez la constante WP_DEBUG

Changez false en true :

define('WP_DEBUG', true);

Si la ligne n’existait pas, ajoutez-la juste avant la ligne /* C'est tout, ne touchez pas à ce qui suit ! Bonne publication. */ (ou /* That's all, stop editing! Happy publishing. */ en anglais). C’est un emplacement standard et sûr.

define('WP_DEBUG', true);

/* C'est tout, ne touchez pas à ce qui suit ! Bonne publication. */
require_once(ABSPATH . 'wp-settings.php');

4️⃣

Étape 4 : Enregistrez et téléchargez le fichier

Enregistrez vos modifications et téléchargez le fichier wp-config.php mis à jour sur votre serveur, en écrasant l’ancienne version. Votre site est maintenant en mode débogage.

📄

Comment afficher ou journaliser les erreurs PHP avec WP_DEBUG_DISPLAY et WP_DEBUG_LOG ?

Activer WP_DEBUG ne suffit pas toujours. WordPress offre des constantes complémentaires pour contrôler la manière dont les erreurs sont gérées : affichées sur le site ou enregistrées dans un fichier.

👀

Afficher les erreurs directement (WP_DEBUG_DISPLAY)

Par défaut, lorsque WP_DEBUG est à true, WP_DEBUG_DISPLAY est également à true. Cela signifie que les erreurs seront affichées directement sur votre site web, dans le navigateur. C’est utile pour un développement local ou sur un environnement de staging où seul vous voyez le site.

Pour le contrôler explicitement, vous pouvez ajouter ou modifier cette ligne dans wp-config.php :

define('WP_DEBUG_DISPLAY', true); // Affiche les erreurs sur le site
define('WP_DEBUG_DISPLAY', false); // Masque les erreurs sur le site

Si vous souhaitez masquer les erreurs à l’écran mais les enregistrer (ce qui est l’approche la plus sûre pour un site en ligne), vous devez définir WP_DEBUG_DISPLAY à false.

📝

Enregistrer les erreurs dans un fichier (WP_DEBUG_LOG)

C’est ici que l’approche professionnelle prend tout son sens. WP_DEBUG_LOG vous permet d’enregistrer toutes les erreurs, avertissements et notices dans un fichier journal sans les afficher aux visiteurs. C’est la méthode à privilégier pour les sites en production ou pour un débogage discret.

Pour l’activer, ajoutez la ligne suivante dans votre fichier wp-config.php, juste après define('WP_DEBUG', true); :

define('WP_DEBUG_LOG', true);

Lorsque cette constante est définie sur true, WordPress crée un fichier nommé debug.log dans le répertoire wp-content/ de votre installation. Toutes les erreurs seront écrites dans ce fichier. Vous pouvez ensuite le consulter via FTP ou le gestionnaire de fichiers sans perturber l’expérience de vos utilisateurs.

⚙️

Configuration complète et sécurisée pour le débogage

La configuration optimale pour un débogage efficace et sécurisé sur un site en ligne est la suivante :

define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', false); // Ne pas afficher les erreurs sur le site
define('WP_DEBUG_LOG', true);    // Enregistrer les erreurs dans wp-content/debug.log

Avec cette configuration, vous activez le mode debug, masquez les erreurs aux visiteurs, et les enregistrez toutes dans un fichier pour une analyse ultérieure. C’est l’approche que nous utilisons systématiquement pour diagnostiquer les problèmes sur les sites de nos clients sans impacter leur image.

⚡

Autres constantes de débogage utiles pour les développeurs

WordPress propose d’autres constantes qui peuvent compléter votre arsenal de débogage :

📜

WP_SCRIPT_DEBUG : Déboguer les scripts et styles

Lorsque cette constante est définie sur true, WordPress utilise les versions de développement (non minifiées) des fichiers JavaScript et CSS de ses composants principaux, des thèmes et des plugins. C’est extrêmement utile si vous rencontrez des problèmes avec des scripts ou des styles.

define('WP_SCRIPT_DEBUG', true);

🔍

SAVEQUERIES : Enregistrer les requêtes de la base de données

Cette constante, lorsqu’elle est définie sur true, enregistre toutes les requêtes SQL effectuées par WordPress dans un tableau PHP. Elle consomme beaucoup de ressources et doit être utilisée avec parcimonie, mais elle est précieuse pour identifier les requêtes lentes ou problématiques qui affectent la performance de votre site.

define('SAVEQUERIES', true);

🧹

Comment interpréter et corriger les erreurs affichées par WP_DEBUG ?

Une fois WP_DEBUG activé, vous verrez apparaître différents types de messages. Comprendre leur signification est la première étape vers la résolution.

• Fatal Errors (Erreurs fatales) : Ce sont les plus graves. Elles arrêtent complètement l’exécution du script PHP et provoquent souvent un écran blanc. Elles sont généralement dues à des erreurs de syntaxe, l’appel d’une fonction inexistante ou l’utilisation d’une classe non définie.

• Warnings (Avertissements) : Moins critiques que les erreurs fatales, les warnings indiquent un problème qui n’arrête pas l’exécution du script, mais qui signale une situation potentiellement problématique. Par exemple, l’inclusion d’un fichier qui n’existe pas.

• Notices (Notifications) : Ce sont les moins graves et souvent les plus nombreuses. Elles indiquent des problèmes mineurs ou des pratiques de codage qui pourraient être améliorées, comme l’utilisation d’une variable non définie. Sur un site bien codé, vous devriez en avoir très peu.

🗺️

Localiser la source de l’erreur

Chaque message d’erreur contient des informations cruciales :

• Type d’erreur : Fatal error, Warning, Notice.

• Description : Une explication brève du problème (ex: « Undefined variable », « Call to undefined function »).

• Chemin du fichier : Le chemin complet vers le fichier où l’erreur s’est produite (ex: /wp-content/plugins/mon-plugin/mon-fichier.php).

• Numéro de ligne : La ligne exacte dans le fichier où le problème est survenu.

Ces informations vous pointent directement vers le problème. Par exemple, si l’erreur mentionne /wp-content/themes/mon-theme/functions.php à la ligne 42, vous savez que le problème vient de votre thème et de cette ligne spécifique.

✅

Stratégies de correction

1. Désactiver les plugins : Si l’erreur pointe vers un plugin, désactivez-les un par un pour identifier le coupable.

2. Changer de thème : Si l’erreur vient du thème, passez temporairement à un thème par défaut (comme Twenty Twenty-Four) pour voir si le problème persiste.

3. Vérifier les mises à jour : Assurez-vous que WordPress, vos thèmes et vos plugins sont tous à jour.

4. Consulter la documentation : Pour les erreurs complexes, une recherche rapide sur Google avec le message d’erreur et le nom du fichier peut vous donner des pistes.

5. Restaurer une sauvegarde : En cas de blocage total, restaurer une sauvegarde récente est souvent la solution la plus rapide.

⚠️

Précautions et bonnes pratiques avec WP_DEBUG en production

Nous l’avons déjà mentionné, mais il est impératif de le répéter : **ne laissez jamais WP_DEBUG_DISPLAY activé sur un site en production.** Exposer les erreurs PHP au public présente plusieurs risques :

• Failles de sécurité : Les messages d’erreur peuvent révéler des chemins de fichiers sur votre serveur, des informations sur les versions de logiciels que vous utilisez, voire des extraits de code. Ces données peuvent être exploitées par des acteurs malveillants pour trouver des vulnérabilités.

• Mauvaise expérience utilisateur : Un site qui affiche des lignes d’erreurs en plein milieu du contenu donne une image non professionnelle et peut effrayer vos visiteurs, les incitant à quitter votre site.

• Impact SEO : Google et les autres moteurs de recherche peuvent interpréter ces erreurs comme un signe de mauvaise qualité ou de dysfonctionnement, ce qui pourrait nuire à votre référencement.

Pour un débogage ponctuel sur un site en production, utilisez toujours la configuration suivante :

define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_LOG', true);

Cela vous permettra de consulter le fichier debug.log sans affecter l’affichage public de votre site. Une fois le problème résolu, **remplacez true par false pour toutes ces constantes** (ou commentez-les) et supprimez le fichier debug.log.

Questions fréquentes

Est-il dangereux de laisser WP_DEBUG activé sur un site en ligne ?

Oui, laisser WP_DEBUG activé avec WP_DEBUG_DISPLAY à true sur un site en ligne est très dangereux. Cela expose des informations techniques sensibles aux visiteurs et aux potentiels attaquants, ce qui peut compromettre la sécurité et l’intégrité de votre site. De plus, cela dégrade l’expérience utilisateur et peut affecter votre référencement.

Où se trouve le fichier debug.log et comment le consulter ?

Lorsque WP_DEBUG_LOG est activé (define('WP_DEBUG_LOG', true);), le fichier debug.log est créé dans le répertoire wp-content/ de votre installation WordPress. Vous pouvez y accéder et le consulter en utilisant un client FTP (comme FileZilla) ou le gestionnaire de fichiers de votre hébergeur web. Il s’agit d’un simple fichier texte que vous pouvez ouvrir avec n’importe quel éditeur de texte.

Que faire si je ne vois aucune erreur après avoir activé WP_DEBUG ?

Si vous avez activé WP_DEBUG et que vous ne voyez aucune erreur, il y a plusieurs possibilités : 1) Il n’y a réellement aucune erreur (rare). 2) Vous avez mal configuré WP_DEBUG_DISPLAY (il devrait être à true pour afficher les erreurs) ou WP_DEBUG_LOG (il devrait être à true pour les enregistrer). 3) Votre hébergeur a des paramètres qui masquent les erreurs PHP, même avec WP_DEBUG activé. Dans ce cas, contactez le support de votre hébergeur.

Puis-je utiliser WP_DEBUG sur un site de production sans risque ?

Oui, mais uniquement avec une configuration sécurisée. Vous devez définir define('WP_DEBUG', true);, define('WP_DEBUG_DISPLAY', false); et define('WP_DEBUG_LOG', true);. Cette configuration permet d’enregistrer toutes les erreurs dans le fichier debug.log sans les afficher publiquement sur votre site. N’oubliez pas de désactiver toutes ces constantes une fois le problème résolu.

Quelle est la différence entre une « Warning » et une « Notice » ?

Une « Warning » (avertissement) indique une situation problématique mais non fatale qui n’interrompt pas l’exécution du script. Par exemple, l’inclusion d’un fichier inexistant. Une « Notice » (notification) est moins grave ; elle signale des problèmes mineurs ou des pratiques de codage qui pourraient être améliorées, comme l’utilisation d’une variable non définie, mais le script continue de s’exécuter normalement. Les « Fatal Errors » (erreurs fatales), elles, arrêtent complètement l’exécution du script.