Configurer Xdebug avec Docker et PhpStorm pour un débogage efficace

Apprends à configurer Xdebug avec Docker et PhpStorm pour un débogage PHP fluide et efficace.

Jérémy 🤘
Jérémy 🤘

Le débogage en PHP peut vite devenir fastidieux avec des var_dump(). Xdebug permet un débogage pas-à-pas et un profilage efficace. Avec Docker, on peut isoler l'environnement et assurer une configuration stable.

Configuration du projet

docker-compose.yaml

Copier
services:
    php:
        build:
            context: .
            dockerfile: ./Dockerfile
        environment:
            - PHP_IDE_CONFIG=serverName=localhost
        extra_hosts:
            - "host.docker.internal:host-gateway"
        volumes:
            - .:/srv
            - xdebug:/xdebug
        restart: "no"

volumes:
    xdebug: 
services:
    php:
        build:
            context: .
            dockerfile: ./Dockerfile
        environment:
            - PHP_IDE_CONFIG=serverName=localhost
        extra_hosts:
            - "host.docker.internal:host-gateway"
        volumes:
            - .:/srv
            - xdebug:/xdebug
        restart: "no"

volumes:
    xdebug: 
  • Monte un volume /srv pour garder le code accessible.
  • Ajoute host.docker.internal pour la communication Xdebug.

Pourquoi utiliser host.docker.internal ?

Lorsque tu fais tourner un conteneur Docker, il est isolé du système hôte. Cela signifie que, par défaut, il ne sait pas comment contacter un service qui tourne sur la machine hôte (comme PhpStorm pour Xdebug).

C’est là qu’intervient host.docker.internal. Cette adresse spéciale permet au conteneur de contacter directement l’hôte sans avoir à deviner son adresse IP.

Dans notre cas, on l’utilise pour Xdebug afin qu’il sache où envoyer les informations de débogage. Voici la ligne de configuration clé :

Copier
xdebug.client_host=host.docker.internal
xdebug.client_host=host.docker.internal

Dockerfile

Copier
FROM php:8.2-fpm

ARG DOCKER_PHP_EXT=2.7.27
ADD https://github.com/mlocati/docker-php-extension-installer/releases/download/${DOCKER_PHP_EXT}/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions

RUN \
    apt-get update && \
    apt-get install -y --fix-missing && \
    install-php-extensions xdebug && \
    apt-get autoremove -y && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    truncate -s 0 /var/log/*log

# Configuration de Xdebug
RUN set -xe; \
    mkdir -p /xdebug && \
    chown -R www-data:www-data /xdebug && \
    chmod -R ugo+rw /xdebug && \
    echo "xdebug.start_with_request=trigger" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.mode=develop,debug,profile" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.discover_client_host=1" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_host=host.docker.internal" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_port=9003" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.idekey=PHPSTORM" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini

WORKDIR /srv
FROM php:8.2-fpm

ARG DOCKER_PHP_EXT=2.7.27
ADD https://github.com/mlocati/docker-php-extension-installer/releases/download/${DOCKER_PHP_EXT}/install-php-extensions /usr/local/bin/
RUN chmod +x /usr/local/bin/install-php-extensions

RUN \
    apt-get update && \
    apt-get install -y --fix-missing && \
    install-php-extensions xdebug && \
    apt-get autoremove -y && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    truncate -s 0 /var/log/*log

# Configuration de Xdebug
RUN set -xe; \
    mkdir -p /xdebug && \
    chown -R www-data:www-data /xdebug && \
    chmod -R ugo+rw /xdebug && \
    echo "xdebug.start_with_request=trigger" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.mode=develop,debug,profile" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.discover_client_host=1" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_host=host.docker.internal" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.client_port=9003" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.idekey=PHPSTORM" >> ${PHP_INI_DIR}/conf.d/docker-php-ext-xdebug.ini

WORKDIR /srv
  • xdebug.start_with_request=trigger : Active Xdebug sur demande.
  • xdebug.mode=develop,debug,profile : Active les fonctionnalités de développement, de débogage et de profilage.
  • xdebug.discover_client_host=1 : Détecte automatiquement l’adresse du client.
  • xdebug.client_host=host.docker.internal : Fait pointer Xdebug vers l’IDE.
  • xdebug.client_port=9003 : Utilise le port 9003 pour le débogage.
  • xdebug.idekey=PHPSTORM : Définit la clé d’IDE pour correspondre à PhpStorm.

Configuration de PhpStorm

Désactiver le break automatique

  • Settings > PHP > Debug : désactiver les options Force break at first line when ...

Configurer le serveur

  • Settings > PHP > Servers :
    • Name : localhost
    • Host : localhost
    • Port : 80
    • Coche Use path mapping
    • Mapper <chemin_de_ton_projet> à /srv

Installer l'extension navigateur

  • Installer Xdebug Helper.
  • Dans ses options :
    • Définir l'IDE key : PHPSTORM.

Conclusion

Ce setup permet d’avoir un environnement de développement PHP propre et fonctionnel, avec un débogage optimisé via Xdebug et PhpStorm. Il est maintenant plus simple d’analyser et de corriger son code efficacement !

Sources