Tutoriel vidéo Xdebug & Docker & PHP : Xdebug avec PHP sous Docker

Dans cette vidéo je vous propose de découvrir comment utiliser Xdebug lorsque PHP est utilisé à l'aide d'un conteneur Docker.

Côté docker

Configuration de l'image Docker

La première étape consiste à installer Xdebug dans le conteneur PHP.
Dans le cas d'une image basée sur alpine :

FROM php:8.1-alpine
RUN apk add --no-cache $PHPIZE_DEPS \
    && pecl install xdebug-3.1.3 \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
WORKDIR /usr/src/myapp
CMD [ "php", "-S", "0.0.0.0:8000"]

Si vous utilisez une image basée sur Ubuntu ou Debian.

FROM php:8.1
RUN pecl install xdebug-3.1.3 \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
WORKDIR /usr/src/myapp
CMD [ "php", "-S", "0.0.0.0:8000"]

Les 2 points importants sont la configuration de l'extension Xdebug :

xdebug.mode permet de choisir le mode. En le mettant en mode debug on active la possibilité d'avoir un debug pas à pas avec des points d'arrêts.
xdebug.client_host permet d'indiquer le nom d'hôte du serveur que Xdebug va essayer de dontacter pour initialiser une session de débogage.

Configuration du container

Pour que l'extension Xdebug puisse se connecter à la session de débogage lancée sur l'hôte il va falloir ajouter l'option de configuration extra_hosts pour brancher le nom d'hôte configuré dans l'option xdebug.client_host.

services:
  php:
    build: ./docker/php
    ports:
      - 8000:8000
    volumes:
      - ./:/usr/src/myapp
    extra_hosts:
      - host.docker.internal:host-gateway

Et voila ! Notre conteneur pourra maintenant se connecter et intéragir avec notre éditeur qui fonctionne sur la machine hôte.

Côté navigateur

L'extension Xdebug est activée par défaut mais la session n'est pas démarrée pour chaque requêtes (sauf avec l'option xdebug.start_with_request=yes). Il est possible de démarrer la session en utilisant un cookie XDEBUG_SESSION que l'on peut activer facilement à l'aide d'une extension :

Cette extension ajoutera un bouton qui vous permettra d'activer la session Xdebug en ajoutant automatiquement le Cookie à vos requêtes.

Côté éditeur

Enfin, la dernière pièce du puzzle est la configuration de l'éditeur afin qu'il écoute les connexions faites par l'extension Xdebug.

VSCode

Pour Visual Studio Code il faudra installer l'extension PHP Debug puis on pourra activer la configuration dans le fichier launch.json placé dans le dossier .vscode.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/usr/src/myapp": "${workspaceFolder}"
            }
        }
    ]
}

Il est important de définir la pathMappings afin que l'éditeur puisse faire correspondre le chemin envoyé par Xdebug au chemin dans le projet.

PHPStorm

Côté PHPStorm il faudra aller dans les préférences puis PHP puis configurer un nouvel interpréteur en utilisant la configuration docker. PHPStorm détectera automatiquement votre fichier docker-compose.yml afin de vous suggérer la liste de services.

Création de l'interpréteur

L'extension Xdebug devrait être automatiquement détectée par l'éditeur et vous pourrez activer l'écoute de la session de débogage dans votre barre d'outil via l'icône qui ressemble à un combiné de téléphone.

Bouton dans la barre d'outil