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 containers qui ne communiquent pas avec PHPStorm, et les configs qui marchent un jour mais plus le lendemain... c'est frustrant.
J'ai perdu pas mal d'heures à faire marcher ce setup. Voici la config qui fonctionne chez moi, et surtout, les pièges à éviter.
Ce dont vous avez besoin:
Docker compose qui utilise une image docker PHP et xdebug déjà installé et activé
Étape 1: Trouver votre IP windows (WSL)
Ouvrir un terminal windows (ou powershell) et executer la commande:
ipconfig
Récupérer l'adresse IP correspondant à la configuration:
Carte Ethernet VEthernet(WSL (Hyper-V firewall))
Étape 2: Créer le fichier Xdebug
Créer un fichier de configuration xdebug.ini (pour ma part je l'ai mis sur la racine du projet) et y ajouter les paramètres nécessaires:
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
Étape 3: Monter le volume dans docker compose ou docker:
Ajouter une ligne dans le sections volumes de docker-compose.yaml pour surcharger le fichier de configuration de xdebug dans le container php
volumes:
- ./xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
(Ou bien directement le copier dans le même chemin dans Dockerfile lors du build si vous n'utilisez pas docker compose)
Étape 4: Configurer PHPStorm:
Relancer votre projet, puis dans PHPStorm:
Activer l'écoute du debugger en cliquant sur l'icône de téléphone en haut à droite
(ou via Run > Start Listening for PHP Debug Connections)Chargez une page de votre application. PHPStorm devrait afficher une popup "Incoming Connection from Xdebug" → Acceptez
Allez dans Settings > PHP > Servers et vérifiez les path mappings :
Le path de votre projet local doit pointer vers la racine de votre projet dans le container
Les pièges courants (et comment les éviter)
L’IP qui change : Si votre config ne fonctionne pas du jour au lendemain, vérifiez votre adresse IP et mettez à jour xdebug.ini
Plusieurs cartes « VEthernet WSL » : Si vous en avez plusieurs, testez chaque IP jusqu’à trouver la bonne. Oui c’est chiant, mais c’est rapide.
Mapping incorrect : Si des liens/fichiers fonctionnent et pas d’autres, verifier bien que le mapping entre le projet sur PHPStorm pointe bien que sur l’absolute path du serveur
Voilà ! Avec cette config, Xdebug devrait fonctionner sans problème dans votre environnement Windows + WSL + Docker + PHPStorm.
Bon débogage !
Top comments (0)