Déboguer avec VSCode, Xdebug et Docker sur Windows8 min read

A chaque environnement de développement sa configuration de Xdebug… Voici plusieurs mois que, chez Naept, nous sommes passés à Docker-compose. Cet article présente la configuration du conteneur Docker et de Visual Studio Code pour pouvoir utiliser Xdebug, tout ça sous Windows.


Point sur le vocabulaire

Avant d’aller plus loin, voici les définitions de quelques termes utilisés dans cet article.

IDE
C’est le sigle anglais pour Integrated Development Environment, qui signifie en français : Environnement de développement. C’est la désignation des logiciels qui permettent d’écrire du code textuel. Nous pourriont très bien écrire du code textuel dans le blocnote de Windows. Mais les IDE vous apportent des fonctionnalités de correction, d’indentation et d’auto-complétion très utiles, et également l’intégration d’une interface graphique pour la base de donnée et les outils de gestion de version.

PECL
Cela signifie PHP Extensions Community Library (ou Bibliothèque communautaire des extensions PHP en français). PECL est un dépôt pour les extensions PHP, fournissant un inventaire de toutes les extensions connues et un hébergement pour ces extensions.

Visual Studio Code (VSCode)
Visual Studio Code, aussi couramment appelé VSCode, est un éditeur de texte très répandu car gratuit, proposé par Microsoft. Il en existe une version libre et open source : Visual Studio Codium.
Il possède une forte communauté qui développe de nombreuses extensions et qui font de VSCode un quasi IDE.

Xdebug
Xdebug est l’outil de débogage de PHP par excellence. Il permet de poser des points d’arrêt dans son code, de faire de l’exécution pas à pas et d’explorer l’état des toutes les variables à des moments précis de l’exécution. Une libération quand les var_dump() et les die() nous ressortent par les yeux !

Configuration

Voici la configuration logicielle dans laquelle l’article a été rédigé. Si vos versions sont trop différentes, il se peut que l’article ne s’applique par parfaitement (n’hésitez pas à nous le faire savoir en commentaires).

Windows 10
Docker : 2.2.0.4
VSCode : 1.37.1
Xdebug : 2.9.4


Ce tutoriel part du principe que Docker pour Windows est installé sur votre machine, ainsi que Visual Studio Code (que je vais appeler VSCode par la suite). Nous allons créer ensemble un simple projet PHP que nous allons pouvoir voir s’exécuter dans VSCode.

Création d’une application PHP à déboguer

Un simple fichier .php

On crée un nouveau dossier local sur votre PC, qu’on ouvre avec VSCode (Fichier -> Ouvrir le dossier…). Et on crée dans ce dossier un fichier index.php qui contiendra le fameux code à déboguer :

<?php
$name = $_REQUEST['name'];
$hello = "Bonjour " . $name . " !";
echo $hello;

Ce code récupère simplement la valeur de name passé en paramètre dans l’url, et l’affiche précédé d’un Bonjour. Cela va nous permettre de voir une bonne partie des variables qu’il est possible d’explorer avec le débogueur.

L’image docker

On va devoir créer une nouvelle image de conteneur pour y installer Xdebug. On crée donc un nouveau fichier appelé dockerfile (ce fichier n’a pas d’extension) et qui contient les lignes de commande suivantes :

FROM php:7.4-apache

# Install Xdebug
RUN pecl install -f xdebug
RUN echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" > /usr/local/etc/php/conf.d/xdebug.ini;

Pour plus de simplicité, on a basé notre image sur l’image officielle php-apache, qui embarque un serveur apache pré-configuré en plus de la dernière version de PHP. On utilise ensuite PECL pour installer Xdebug, enfin on crée un fichier d’initialisation avec la ligne qui va bien pour activer Xdebug dans le conteneur.

Docker Compose

Toujours dans le même dossier, on crée un nouveau fichier nommé docker-compose.yml. On va y écrire les instructions pour lancer le conteneur qu’on vient de décrire :

version: '3.5'

services:

  # Our application to debug
  app:
    container_name: tuto-xdebug
    build:
      context: ./
      dockerfile: ./dockerfile
    ports:
      - '80:80'
    volumes:
        - './index.php:/var/www/html/index.php'
    environment:
      XDEBUG_CONFIG: remote_host=host.docker.internal remote_port=9000 remote_enable=1

Lignes 6 à 10
On a ici un seul service app qui construit un conteneur nommé tuto-xdebug à partir du fichier dockerfile présent à la racine du dossier courant.

Lignes 11 à 14
On expose son port 80 sur notre port 80, et on crée un lien entre notre fichier index.php et le fichier index.php du dossier /var/www/html de notre container (C’est sur ce dossier que pointe le serveur apache embarqué).

Lignes 15 à 16
Enfin on configure Xdebug. Docker fournit une adresse DNS particulière host.docker.internal pour se connecter à son host.

En effet, on ne pourrait utiliser ni localhost, puisque notre VSCode se trouve en dehors de docker, ni l’adresse IP de notre machine qui change en fonction du réseau auquel on est connecté. Je précise que c’est bien Xdebug qui se connecte à VSCode, pas l’inverse. Par convention, on connecte Xdebug au port 9000, mais si on voulait pouvoir espionner plusieurs containers en même temps avec Xdebug, on devrait les répartir sur différents ports.

Lancement du container

Voilà notre application est prête. Reste à la lancer. Pour cela on ouvre un terminal, on se déplace jusqu’à la racine de notre dossier, et on tape la commande docker-compose up.

On peut vérifier que notre application fonctionne correctement en ouvrant notre navigateur préféré et en se rendant à l’URL localhost?name=Julien.

On peut constater que notre code fonctionne bien et affiche “Bonjour Julien !”.

L’extension VSCode

VSCode est un simple éditeur de texte. Ce sont ses extensions qui lui donnent toute sa puissance et en font presque un environnement de développement complet (IDE).

Celle qui nous intéresse aujourd’hui permet de placer des points d’arrêts dans le code (même des points d’arrêts conditionnels !), d’exécuter les instructions du code pas à pas, d’explorer des variables, bref tout ce qu’on est en droit d’exiger d’un bon débogueur… Elle s’appelle PHP Debug et est éditée par un certain Felix Becker.

Installation de l’extension

Pour l’installer dans VSCode, il faut :

  • cliquer sur l’icone “Extensions” sur la barre de gauche (ou Ctrl+Maj+X)
  • puis utiliser le champs de recherche pour trouver l’extension (taper xdebug)
  • et l’installer (clic sur le petit bouton vert “Install”).
L’extension PHP Debug de Felix Becker

Pour fonctionner, cette extension nécessite que PHP soit installé en local sur votre PC. On peut vérifier qu’il est installé en tapant la commande php -version dans une invite de commande. Elle devrait être reconnue et vous donner la version de PHP actuellement installée.

Si ce n’est pas le cas, vous pouvez télécharger la dernière version (Non Thread Safe) sur ce site.

Configuration d’un écouteur

L’extension PHP Debug est capable de gérer plusieurs configurations si on a besoin d’écouter plusieurs instances d’Xdebug. On va n’en créer qu’une seule ici, pour notre conteneur.

Pour ce faire, il faut :

  • cliquer sur l’icône “déboguer” sur la barre de gauche (ou Ctrl+Maj+D)
  • puis cliquer sur la petite roue dentée “Ouvrir launch.json” à côté du menu déroulant en haut du volet latéral gauche
  • puis sur PHP dans la liste des environnements proposés. Un dossier caché .vscode contenant le fichier launch.json est créé à la racine de notre projet.

On en déduit que la configuration de notre extension est liée à notre projet, ce qui est approprié puisque tous nos projets n’utilisent pas forcément Docker et auront probablement des configurations différentes.

Notre fichier launch.json ouvert, on constate qu’il contient déjà 2 configurations que l’on peut supprimer ou non, peut importe. Nous allons en créer une nouvelle :

{
    "name": "Listen for XDebug on Docker App",
    "type": "php",
    "request": "launch",
    "port": 9000,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
    },
    "xdebugSettings": {
        "max_data": 65535,
        "show_hidden": 1,
        "max_children": 100,
        "max_depth": 5
    }
},

Ligne 5
On portera une attention particulière au numéro de port utilisé, qui doit être identique à celui donné dans notre fichier docker-compose.yml.

Ligne 6
Le pathMapping également doit être correct ; ne pas utiliser de chemin absolue ou relatif, mais bien les variables fournies par VSCode.

Lignes 9 à 14
Les valeurs de xdebugSettings ont été pompées sur le web et peuvent (doivent ?) être ajustées suivant le besoin.

Place maintenant à la magie ! Voir notre code s’exécuter dans VSCode.

C’est parti pour le débogage !

Maintenant que tout est prêt, on va pouvoir placer notre premier point d’arrêt.

Pour cela, dans le fichier index.php (ouvert dans VSCode), on va placer notre souris à gauche du numéro de la ligne avant laquelle on veut mettre en pause l’exécution. Un point rouge sombre apparaît. Si on clique il devient rouge vif et reste en place. Ça y est le point d’arrêt est placé.

Dans le volet latéral gauche, on s’assure que notre configuration est bien celle sélectionnée dans le menu déroulant, puis on clique ensuite sur le triangle vert “Démarrer le débogage”.

Une nouvelle petite barre contenant 6 boutons apparaît en haut à droite de VSCode. Ce dernier est maintenant fin prêt à intercepter la prochaine exécution.

Enfin on rafraîchit notre page web (localhost?name=Julien) et Tadaa ! L’execution du code s’arrête sur notre point d’arrêt !

VSCode nous surligne la ligne sur laquelle l’exécution s’est arrêtée. Dans le volet de gauche on peut naviguer et voir les valeurs des variables locales et globales.

On peut également les voir en survolant les variables directement dans le code, et la nouvelle barre en haut à droite permet de passer les instructions une à une, d’arrêter ou de continuer l’exécution.


Merci d’avoir lu cet article. Vous trouverez le code complet ici.

N’hésitez pas à commenter. Bonne journée !

Related Posts

Leave a Reply