# Xdebug et VS Code : déboguer WordPress pas à pas sans un seul var_dump

> Installer Xdebug, configurer launch.json et mapper les chemins en Docker : la méthode pour poser un point d'arrêt dans un hook WordPress et l'observer s'exécuter.

- Auteur : Clément Hadrot
- Publié le : 2020-04-08
- Mis à jour le : 2020-04-08
- Catégorie : Outils & workflow
- URL : https://wpmoderne.dev.wordpress-developpement.fr/outils/xdebug-vscode-debogage-local/

## L’essentiel

- Installation Xdebug et réglages php.ini essentiels
- launch.json pour VS Code, avec mapping de chemins
- Points d'arrêt utiles dans les hooks WordPress

« Ç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

> L'essentiel à retenir : Installation Xdebug et réglages php.ini essentiels ; launch.json pour VS Code, avec mapping de chemins ; Points d'arrêt utiles dans les hooks WordPress

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.yml` pour 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())` dans `wp-config.php` pour 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.