Laravel + Xdebug dans Docker : Débogage, Couverture & Profilage

Faire marcher Xdebug dans Docker ne devrait pas prendre des heures. Mais c’est souvent le cas, parce que chaque guide suppose une image de base différente et la moitié des options de config sont fausses pour votre setup.

Voici la config qui marche avec Amazon Linux 2023, PHP 8.2 et VSCode. Débogage pas à pas, couverture de code, profilage. Le package complet.

Étape 1 : Créer le Dockerfile**

Ce Dockerfile :

Utilise Amazon Linux 2023
Installe PHP 8.2, Composer et les dépendances Laravel
Installe Xdebug pour le débogage et le profilage
Expose les ports de Laravel (80) et Xdebug (9003)

FROM public.ecr.aws/amazonlinux/amazonlinux:2023
USER root

# Installer PHP 8.2 et les outils essentiels
RUN dnf install -y php8.2 php-pear php8.2-devel gcc make autoconf wget git unzip nginx

# Installer les extensions PHP
RUN dnf install -y php-{cli,pdo,common,curl,mbstring,gd,mysqlnd,gettext,bcmath,json,xml,fpm,intl}

# Installer Composer
RUN curl -sS [https://getcomposer.org/installer](https://getcomposer.org/installer) | php -- --install-dir=/usr/local/bin --filename=composer

# Installer et configurer Xdebug
RUN pecl install xdebug
RUN echo "zend_extension=$(find /usr/lib64/php/modules/ -name xdebug.so)" > /etc/php.d/15-xdebug.ini && \
    echo "xdebug.mode=debug,develop,coverage,profile" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.client_host=host.docker.internal" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.start_with_request=trigger" >> /etc/php.d/15-xdebug.ini && \
    echo "xdebug.client_port=9003" >> /etc/php.d/15-xdebug.ini

WORKDIR /var/www/html
EXPOSE 80 9003
CMD ["/bin/bash"]

Étape 2 : Construire et exécuter Docker**

1. Construire l’image

docker build --no-cache -t laravel-xdebug .

2. Exécuter le conteneur

docker run -d -p 80:80 -p 9003:9003 --name laravel-xdebug laravel-xdebug

3. Vérifier Xdebug

docker exec -it laravel-xdebug bash
php -m | grep xdebug

Étape 3 : Installer Laravel dans Docker**

À l’intérieur du conteneur :

cd /var/www/html
composer create-project --prefer-dist laravel/laravel .
php artisan serve --host=0.0.0.0 --port=80

Visitez : http://localhost:80

Étape 4 : Configurer VSCode pour le débogage**

Installez l’extension PHP Debug dans VSCode.
Créez .vscode/launch.json dans votre projet Laravel :

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Écouter Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

Démarrez le débogage dans VSCode (Exécuter > Démarrer le débogage).
Définissez des points d’arrêt dans les contrôleurs/routes Laravel.

Étape 5 : Débogage et PHPUnit avec couverture**

Déclencher le débogage

Requêtes web : http://localhost:80/home?XDEBUG_SESSION_START=1
CLI (Commandes Artisan) :
```
XDEBUG_SESSION=1 php artisan migrate
```

Tests PHPUnit :

XDEBUG_SESSION=1 php artisan test --filter=MaClasseDeTest

Exécuter PHPUnit avec couverture

php artisan test --coverage-text
php artisan test --coverage-html rapport-couverture/

Étape 6 : Résoudre les problèmes de connexion Xdebug**

Si vous voyez :

Xdebug: [Step Debug] N'a pas pu se connecter au client de débogage. Tentative : host.docker.internal:9003

Essayez ces étapes :

1️⃣ Vérifiez si Xdebug est installé :

php -m | grep xdebug

2️⃣ Vérifiez la configuration de Xdebug :

php -i | grep xdebug

3️⃣ Exposez le port 9003 :

docker run -d -p 80:80 -p 9003:9003 ...

4️⃣ Utilisez l’adresse IP de votre hôte au lieu de host.docker.internal :

ip route | awk '/default/ { print $3 }'

Mettez à jour :

xdebug.client_host=VOTRE_IP_HOTE

5️⃣ Vérifiez si Xdebug est en écoute :

netstat -an | grep 9003

6️⃣ Déclenchez Xdebug manuellement : Ajoutez ?XDEBUG_SESSION_START=1 aux URL ou utilisez XDEBUG_SESSION=1 en CLI.

C’est tout

Débogage pas à pas, rapports de couverture et profilage dans un seul setup Docker. Le truc qui bloque la plupart des gens, c’est host.docker.internal qui ne résout pas. Si c’est votre cas, l’étape 6 a la solution.