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

> Activer WP_DEBUG_LOG ne suffit pas toujours à retrouver l'erreur rapidement. Voici les réglages et les bonnes habitudes qui font vraiment gagner du temps au quotidien.

- Auteur : Clément Hadrot
- Publié le : 2022-01-11
- Mis à jour le : 2022-01-11
- Catégorie : Tips
- URL : https://wpmoderne.dev.wordpress-developpement.fr/tips/wp-debug-log-bons-reflexes-debogage-wordpress/

## L’essentiel

- WP_DEBUG_LOG écrit les erreurs sans les afficher au visiteur
- error_log() trace ses propres points de contrôle
- Un debug.log qui grossit sans limite doit être surveillé

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).

> L'essentiel à retenir : WP_DEBUG_LOG écrit les erreurs sans les afficher au visiteur ; error_log() trace ses propres points de contrôle ; Un debug.log qui grossit sans limite doit être surveillé

## 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.