WP_DEBUG_LOG : les bons réflexes pour déboguer WordPress efficacement

Face à un comportement inattendu sur un site WordPress, le réflexe le plus efficace reste souvent le plus simple : activer la journalisation des erreurs PHP dans un fichier dédié, plutôt que de les laisser s’afficher (ou pire, disparaître silencieusement) en production. La constante WP_DEBUG_LOG, couplée à quelques réglages complémentaires, transforme un débogage à l’aveugle en investigation méthodique.

Cet article détaille la configuration recommandée, les pièges classiques (un fichier de log qui grossit indéfiniment, des notices PHP qui noient l’erreur qui compte vraiment), et quelques habitudes qui font gagner un temps précieux.

La configuration de base dans wp-config.php

Trois constantes suffisent pour un environnement de développement bien réglé, à placer avant la ligne /* C'est tout, ne touchez pas à ce qui suit ! Bonne publication. */ du fichier wp-config.php :

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

Cette combinaison est essentielle à comprendre : WP_DEBUG active le mode débogage général, WP_DEBUG_LOG redirige les erreurs vers un fichier wp-content/debug.log plutôt que de les laisser s’afficher, et WP_DEBUG_DISPLAY à false empêche justement cet affichage direct à l’écran. Sans ce dernier réglage, une erreur PHP peut s’afficher en clair sur une page publique, un risque de sécurité autant qu’un problème d’image pour le site.

Où trouver le fichier de log

Par défaut, le fichier se situe dans wp-content/debug.log. Il est possible de personnaliser son emplacement, ce qui est recommandé pour éviter qu’il ne soit accidentellement exposé publiquement s’il se trouve dans un répertoire accessible par HTTP :

define( 'WP_DEBUG_LOG', WP_CONTENT_DIR . '/logs/debug.log' );

Le répertoire choisi doit rester en dehors de tout accès web direct, ou protégé par une règle serveur dédiée, car un fichier de log peut contenir des informations sensibles (chemins serveur, parfois des données de requêtes).

Suivre le log en temps réel

Plutôt que de recharger un fichier texte à répétition, la commande tail en ligne de commande permet de suivre les nouvelles entrées au fur et à mesure qu’elles s’écrivent, particulièrement utile pendant une session de débogage active :

tail -f wp-content/debug.log

Sur certains systèmes où le fichier est régulièrement remplacé plutôt que simplement complété (rotation de logs, certains outils de synchronisation), l’option -F majuscule est plus fiable : elle continue de suivre le fichier même s’il est recréé entre-temps.

tail -F wp-content/debug.log

Écrire ses propres traces avec error_log

Au-delà des erreurs PHP natives, il est souvent utile d’ajouter ses propres points de trace dans le code, pour comprendre le déroulement exact d’une logique métier complexe. La fonction native PHP error_log() écrit dans le même fichier configuré par WP_DEBUG_LOG :

error_log( 'Valeur du panier avant calcul : ' . print_r( $panier, true ) );

Pour des structures complexes (tableaux, objets), combiner print_r() avec le second paramètre à true évite d’écrire l’objet brut, illisible dans un fichier texte.

Filtrer le bruit des notices PHP

Sur un projet qui mélange du code ancien et des extensions tierces, le fichier de log peut vite se remplir de notices et de warnings sans gravité réelle (variable non définie, index de tableau manquant), qui noient l’erreur véritablement importante. Une astuce consiste à chercher spécifiquement les entrées de type Fatal error ou Uncaught Error, généralement les plus critiques :

grep -i "fatal error" wp-content/debug.log
grep -i "uncaught" wp-content/debug.log

Surveiller la taille du fichier

Un fichier debug.log oublié en production, ou simplement actif depuis plusieurs mois sur un environnement de développement partagé, peut atteindre plusieurs centaines de mégaoctets. Un contrôle régulier, ou une rotation automatisée via logrotate côté serveur, évite ce désagrément :

du -h wp-content/debug.log

Sur un serveur Linux, une entrée logrotate dédiée permet d’archiver et de vider le fichier automatiquement chaque semaine, sans intervention manuelle.

Checklist avant de passer en production

• Vérifier que WP_DEBUG_DISPLAY reste à false, y compris en développement
• Désactiver WP_DEBUG et WP_DEBUG_LOG sur l’environnement de production, ou les restreindre à un accès protégé
• Vérifier que le fichier de log n’est jamais accessible publiquement par une URL directe
• Nettoyer ou archiver le fichier de log avant qu’il ne devienne ingérable

Un site en production avec WP_DEBUG_DISPLAY activé par mégarde affiche parfois des chemins serveur complets à n’importe quel visiteur : une vérification de routine avant chaque mise en ligne.

En résumé

Trois constantes bien réglées dans wp-config.php transforment radicalement l’expérience de débogage sous WordPress : plus besoin de deviner ce qui se passe, il suffit de suivre le fichier de log en temps réel. Le vrai savoir-faire réside ensuite dans la discipline : filtrer le bruit, surveiller la taille du fichier, et ne jamais laisser ces réglages actifs sans contrôle sur un site accessible au public.