Aller au contenu

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

La configuration Xdebug + Docker + Laravel qui a finalement fonctionné — après des heures à débugger le débuggeur.

· 5 min read ·
Laravel Xdebug Docker Amazon Linux Débogage

TL;DR : Faire marcher Xdebug dans Docker avec Laravel sur Amazon Linux 2 necessite les bons reglages xdebug.ini, host.docker.internal comme client host, et le bon mapping de chemins dans l’IDE. Ce guide couvre le debogage pas-a-pas, la couverture de code et le 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**

  1. Installez l’extension PHP Debug dans VSCode.
  2. 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}"
      }
    }
  ]
}
  1. Démarrez le débogage dans VSCode (Exécuter > Démarrer le débogage).
  2. 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.

Questions frequentes

Pourquoi Xdebug ne se connecte pas a mon IDE depuis Docker ?

La cause la plus frequente est le reglage client_host. Utilisez host.docker.internal sur Docker Desktop, ou l’IP de l’hote sur Linux. Verifiez aussi que votre IDE ecoute sur le bon port (9003 par defaut pour Xdebug 3).

Comment changer de mode Xdebug sans reconstruire l’image ?

Definissez XDEBUG_MODE comme variable d’environnement dans votre docker-compose.yml. Changez-le en debug, coverage ou profile et redemarrez le conteneur — pas de rebuild necessaire.

Est-ce que Xdebug ralentit l’environnement de developpement ?

Seulement quand il est actif. Configurez xdebug.start_with_request=trigger au lieu de yes, et utilisez une extension navigateur pour envoyer le cookie de declenchement uniquement quand vous en avez besoin.

Cette configuration fonctionne-t-elle avec Amazon Linux 2023 ?

Oui, avec des ajustements mineurs. Amazon Linux 2023 utilise dnf au lieu de yum. La configuration Xdebug elle-meme reste identique.