Chapitre 4.5 — Débogage : WP_DEBUG, logs & Xdebug

⏱️ TL;DR — Déboguer WordPress, c’est d’abord voir les erreurs : activez WP_DEBUG + WP_DEBUG_LOG pour les écrire dans wp-content/debug.log. Ajoutez Query Monitor (un plugin) pour inspecter requêtes SQL, hooks, appels HTTP et perf. Pour le pas-à-pas, branchez Xdebug à votre IDE. Enfin, gardez le réflexe « purger les caches » quand un changement « ne s’applique pas ». Un bon setup de débogage transforme un « écran blanc » angoissant en message d’erreur précis.

🎯 Objectifs

• Activer et exploiter les logs de débogage.
• Utiliser Query Monitor pour l’inspection runtime.
• Mettre en place Xdebug (pas-à-pas) avec l’IDE.
• Diagnostiquer l’« écran blanc de la mort » (WSOD).

1. Voir les erreurs (le socle)

Dans wp-config.php (ch. 4.2), en développement :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );      // → wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // ne pas casser l'affichage : on lit le log
define( 'SCRIPT_DEBUG', true );      // assets non minifiés

Puis, dans votre code, écrivez dans le log :

error_log( 'Valeur de $data : ' . print_r( $data, true ) );

Et suivez le fichier en direct :

tail -f wp-content/debug.log     # (ou via WP-CLI / l'outil de votre env local)

⚠️ Piège — En production, WP_DEBUG_DISPLAY doit rester false (ou WP_DEBUG désactivé) : afficher les erreurs PHP aux visiteurs fuit des chemins de fichiers et des indices d’attaque. En dev, on logue (WP_DEBUG_LOG) plutôt que d’afficher, pour ne pas casser la mise en page pendant qu’on travaille.

2. Query Monitor : le tableau de bord du dev

Query Monitor est un plugin incontournable. Une fois activé, il ajoute une barre d’outils qui détaille, pour chaque page :

• les requêtes SQL (nombre, durée, les plus lentes, les doublons) ;
• les hooks déclenchés et les callbacks attachés ;
• les appels HTTP sortants (API externes) ;
• les erreurs PHP et notices ;
• le temps et la mémoire consommés ;
• l’objet WP_Query de la page, les templates chargés, les capabilities vérifiées.

💡 Pour un dev React — Query Monitor, c’est vos DevTools pour WordPress : l’onglet « Network » (requêtes SQL/HTTP), un profileur (temps/mémoire), et une vue des hooks (comme un arbre de composants/événements). C’est l’outil n°1 pour comprendre ce que fait réellement une page — et repérer les requêtes N+1 (Partie 11, perf).

3. Xdebug : le pas-à-pas

Pour déboguer vraiment (points d’arrêt, inspection de variables, pile d’appels), on utilise Xdebug, l’extension de débogage de PHP, connectée à l’IDE (VS Code + extension PHP Debug, ou PhpStorm).

Étapes :

1. Xdebug installé dans l’environnement (LocalWP l’inclut ; wp-env/Docker : à activer dans l’image PHP).
2. Configurer l’IDE pour écouter (port 9003 par défaut) et mapper les chemins (path mappings).
3. Poser un point d’arrêt, recharger la page → l’exécution s’arrête, vous inspectez $variables, la stack, vous avancez pas à pas.

C’est incomparablement plus efficace que semer des error_log() partout pour un bug complexe.

📚 Aller plus loin — Avec wp-env, on active Xdebug via wp-env start --xdebug=debug et on configure VS Code avec le bon path mapping (le code local ↔ /var/www/html/wp-content/... dans le conteneur). Le mapping est l’étape qui coince le plus souvent : sans lui, l’IDE ne relie pas les points d’arrêt aux fichiers.

4. L’écran blanc de la mort (WSOD)

Une page totalement blanche = une erreur fatale PHP non affichée. Démarche :

1. Activez WP_DEBUG + WP_DEBUG_LOG et rechargez → lisez debug.log (le message et le fichier/ligne fautifs).
2. Souvent : un plugin ou le thème incompatible (surtout après une mise à jour ou un passage PHP 8). WordPress a une protection contre les erreurs fatales qui met le site en « mode récupération » et envoie un e-mail à l’admin avec un lien pour désactiver le fautif.
3. En dépannage : désactiver les plugins (via WP-CLI wp plugin deactivate --all, ou en renommant wp-content/plugins), puis réactiver un par un pour isoler le coupable.
4. Vérifier la version de PHP (une syntaxe incompatible avec PHP 8 est fréquente).

5. Le réflexe « caches »

Comme dans beaucoup de CMS, un changement qui « ne s’applique pas » est souvent un cache : cache d’objets (Redis/Memcached), plugin de cache de pages, cache de l’opcode PHP (OPcache), ou cache navigateur. Réflexe : purger les caches (plugin de cache, wp cache flush, redémarrer PHP en dev) avant de conclure à un bug. On approfondit le cache en Partie 11 (perf).

✏️ Exercices

1. Quelle combinaison de constantes permet de loguer les erreurs sans les afficher aux visiteurs ?
2. Vous avez une page très lente : quel outil consultez-vous et que cherchez-vous en priorité ?
3. Un site affiche un écran blanc après une mise à jour de plugins. Décrivez votre démarche.

🧠 Quiz de révision

Chapitre suivant : La base de données & ses outils.