06/03/2026

Installer Xdebug avec Docker et VS Code

Schéma de fonctionnement

Navigateur
     │
     │ Requête HTTP
     ▼
Serveur Web (Docker)
     │
     │ exécute
     ▼
PHP + Xdebug
     │
     │ connexion debug (port 9003)
     ▼
VS Code (extension PHP Debug)
     │
     ▼
Breakpoint déclenché dans l'éditeur

1. Installer Xdebug dans l’image Docker

Dans votre Dockerfile, ajoutez l’installation de Xdebug :

RUN install-php-extensions xdebug

2. Configuration dans docker-compose

Ajoutez la configuration suivante dans votre service php :

php:
  environment:
    PHP_IDE_CONFIG: "serverName=project"
    XDEBUG_MODE: "debug"
    XDEBUG_CONFIG: "client_host=host.docker.internal log=/var/www/project/var/log/xdebug.log start_with_request=yes"
  extra_hosts:
    - "host.docker.internal:host-gateway"

Explication

• PHP_IDE_CONFIG : nom du serveur utilisé par l’IDE
• XDEBUG_MODE=debug : active le mode debug
• client_host=host.docker.internal : permet au conteneur de contacter votre machine
• log=... : fichier de log Xdebug
• start_with_request=yes : démarre le debug automatiquement
• extra_hosts : permet à Docker de résoudre host.docker.internal

3. Configuration VS Code

Créer le fichier :

.vscode/launch.json

Contenu :

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "log": true,
      "pathMappings": {
        "/var/www/project": "${workspaceFolder}"
      }
    }
  ]
}

Explication

• port : port utilisé par Xdebug (9003 par défaut avec Xdebug 3)
• pathMappings : correspondance entre le chemin dans le conteneur et sur votre machine (la partie de gauche c’est dans le conteneur et la partie de droite c’est sur ta machine)

4. Installer l’extension VS Code

Extension à installer :

Name: PHP Debug
Id: xdebug.php-debug
Publisher: xdebug
Version: 1.40.0

Lien :

https://open-vsx.org/vscode/item?itemName=xdebug.php-debug

5. Tester le fonctionnement

Test simple

Ajoutez temporairement dans votre code :

xdebug_break();

Si le debug fonctionne, VS Code s’arrêtera à cette ligne.

Test via URL

Ajoutez dans l’URL :

?XDEBUG_SESSION=1

Exemple :

http://localhost:8000/?XDEBUG_SESSION=1

6. Extension navigateur (facultatif)

Extension Firefox :

https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/

Elle permet d’activer ou désactiver Xdebug facilement depuis le navigateur.