Configuration Xdebug sur PHPSTORM + Windows + WSL + Docker

Source: Dev.to

Introduction

Si vous développez en PHP sous Windows avec WSL et Docker, vous avez probablement déjà galéré avec Xdebug. Entre les IP qui changent, les conteneurs qui ne communiquent pas avec PHPStorm, et les configurations qui fonctionnent un jour puis plus le lendemain… c’est frustrant. Voici la configuration qui fonctionne chez moi, ainsi que les pièges à éviter.

Docker compose avec Xdebug installé

Utilisez une image Docker PHP où Xdebug est déjà installé et activé.

Récupérer l’adresse IP de WSL

1. Ouvrez un terminal Windows (ou PowerShell).

2. Exécutez la commande :

   ipconfig

3. Notez l’adresse IP correspondant à votre configuration WSL (par ex. 172.22.128.1).

Créer le fichier xdebug.ini

Placez‑le à la racine du projet (ou à l’endroit de votre choix) et ajoutez :

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=172.22.128.1   ; Remplacez par votre IP WSL
xdebug.discover_client_host=0
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.cli_color=1

Surcharger la configuration dans le conteneur

Ajoutez une ligne dans la section volumes de votre docker-compose.yaml :

volumes:
  - ./xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

Alternative : copiez le fichier directement dans le même chemin via le Dockerfile si vous n’utilisez pas Docker Compose.

Relancer le projet

Redémarrez vos services Docker pour que la nouvelle configuration soit prise en compte.

Configurer PHPStorm

1. Activez l’écoute du débogueur en cliquant sur l’icône du téléphone en haut à droite.
2. Chargez une page de votre application. PHPStorm doit afficher une popup “Incoming Connection from Xdebug” → cliquez sur Accepter.
3. Allez dans Settings > PHP > Servers et vérifiez les path mappings afin que le chemin absolu du projet sur le serveur corresponde à celui de votre projet local.

Pièges courants (et comment les éviter)

L’IP qui change

Si la configuration cesse de fonctionner du jour au lendemain, revérifiez votre adresse IP et mettez‑à‑jour xdebug.ini.

Plusieurs cartes « VEthernet WSL »

Si vous avez plusieurs interfaces, testez chaque IP jusqu’à trouver la bonne. C’est fastidieux mais nécessaire.

Mapping incorrect

Si certains fichiers fonctionnent et d’autres pas, assurez‑vous que le mapping entre le projet PHPStorm et le chemin absolu du serveur est correct.

Conclusion

Avec cette configuration, Xdebug devrait fonctionner sans problème dans votre environnement Windows + WSL + Docker + PHPStorm. Bon débogage !