« Ça devrait marcher » est la phrase la plus dangereuse du développement WordPress. Face à un hook qui ne se déclenche pas ou une valeur inattendue dans $_POST, la tentation est grande de semer des var_dump() un peu partout puis de les oublier dans le code livré. Xdebug couplé à VS Code règle ce problème : on pose un point d’arrêt, on observe l’état réel du programme, et on avance ligne par ligne.
Cet article couvre l’installation et la configuration minimale pour arriver à un vrai débogage pas à pas, y compris quand WordPress tourne dans un conteneur Docker ou dans Local. Le profilage de performance, qui utilise aussi Xdebug mais dans un mode différent, fait l’objet d’un autre sujet.
Installer Xdebug
Sur une installation locale classique avec PHP compilé sur la machine, l’extension s’installe via PECL :
pecl install xdebug
Dans un conteneur Docker basé sur une image PHP officielle, on l’ajoute au Dockerfile :
RUN pecl install xdebug && docker-php-ext-enable xdebug
Il faut ensuite configurer trois réglages dans php.ini (ou un fichier dédié xdebug.ini) :
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
Depuis Xdebug 3, le port par défaut est 9003 (contre 9000 pour Xdebug 2) : une confusion fréquente quand on copie une configuration trouvée en ligne datant d’avant 2020.
Configurer launch.json dans VS Code
Avec l’extension « PHP Debug » installée, VS Code génère un fichier .vscode/launch.json. La configuration minimale ressemble à ceci :
{
"version": "0.2.0",
"configurations": [
{
"name": "Écouter Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
}
]
}
Le champ pathMappings est le point le plus souvent oublié, et pourtant le plus critique en environnement conteneurisé.
Mapper les chemins en Docker ou Local
Sans mapping correct, VS Code reçoit bien la notification de point d’arrêt atteint, mais ne parvient pas à retrouver le fichier source correspondant sur la machine hôte — il ouvre alors un onglet vide ou affiche « source not available ». La clé de gauche correspond au chemin tel que vu depuis le conteneur, la valeur de droite au chemin sur la machine de développement.
- Avec Docker Compose, vérifier le point de montage du volume dans
docker-compose.ymlpour connaître le chemin exact côté conteneur - Avec Local (anciennement Local by Flywheel), le chemin côté conteneur suit généralement
/app/public - En cas de doute, ajouter temporairement
error_log(getcwd())danswp-config.phppour confirmer le chemin réel
Déclencher Xdebug depuis le navigateur
Une fois xdebug.start_with_request=yes activé, Xdebug tente de se connecter à chaque requête PHP, ce qui ralentit sensiblement le site en développement. Une alternative plus légère consiste à repasser en xdebug.start_with_request=trigger et à activer le débogage à la demande via un cookie ou un paramètre d’URL ?XDEBUG_TRIGGER=1, posé par l’extension navigateur officielle « Xdebug helper ».
Points d’arrêt utiles dans les hooks WordPress
WordPress exécute son cycle de vie à travers une longue chaîne de hooks. Quelques emplacements de point d’arrêt particulièrement rentables :
| Hook | Ce qu’on y observe |
|---|---|
pre_get_posts | La requête WP_Query avant son exécution, utile pour un point d’arrêt sur $query->query_vars |
save_post | Les métadonnées reçues juste avant leur enregistrement |
rest_pre_dispatch | La requête REST API avant son traitement par le contrôleur |
template_redirect | Le moment où WordPress choisit le template à charger |
Un point d’arrêt posé sur save_post permet par exemple d’inspecter en direct le contenu de $_POST['acf'] lors de l’enregistrement d’une fiche produit, sans ajouter la moindre instruction de log.
Pour aller plus loin
Xdebug consomme des ressources et n’a rien à faire activé en production : un simple oubli de configuration peut ralentir un serveur de façon spectaculaire. Le réflexe à prendre est de le limiter strictement à l’environnement local, avec xdebug.mode=off par défaut sur les autres environnements. Une fois cette configuration en place, le temps passé à traquer un bug complexe se réduit souvent de moitié : observer l’état réel du programme vaut toujours mieux que le deviner.
