XDebug inside a docker container

• 02, 25, 2021
•  bullgare
•  php
• No Comments.

That’s how you can debug your php app running in a docker container.

Prepare your service

docker-compose.yml

  my-service:
    build:
      context: .
      dockerfile: ./Dockerfile
      target: my-service
      args:
        GITHUB_TOKEN: ${GITHUB_TOKEN}
    container_name: my-service
    hostname: my-service
    working_dir: /home/www-data/my-service
    ports:
      - "8080:80"
      - "443:443"
    volumes:
      - .:/home/www-data/my-service
    networks:
      - my-network
    environment:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
      COMPOSER_AUTH: '{"github-oauth":{"github.com": "${GITHUB_TOKEN}"}}'
      XDEBUG_SESSION: "PHPSTORM" # that's very important

assets/xdebug.ini

xdebug.remote_enable=1
xdebug.mode=debug
xdebug.remote_autostart=1
xdebug.start_with_request=yes
xdebug.remote_connect_back=off
xdebug.discover_client_host=off
xdebug.remote_host=host.docker.internal
# xdebug.remote_host=10.254.254.254 ; use this to configure it manually
xdebug.client_host=host.docker.internal
xdebug.remote_port=9005
xdebug.client_port=9005
# is replaced with export XDEBUG_SESSION=PHPSTORM
xdebug.idekey="PHPSTORM"
xdebug.max_nesting_level=1500

Dockerfile

COPY assets/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && docker-php-source delete

Prepare your PhpStorm

• Settings → Languages & Frameworks → PHP → Debug → XDebug → Debug port: 9005
• Edit Run configurations → Edit configurations → + → PHP Remote Debug
  • Filter debug connections by IDE key → IDE key (Session id): PHPSTORM
  • Also you need to add a server (in «Filter debug connections by IDE key» section click on «…»):
    • Host: 127.0.0.1
    • Port: 9005
    • Debugger: XDebug
    • Use path mappings:
      : /home/www-data/my-service

Useful links

https://gist.github.com/bullgare/0d9cc2e8ff896ca651286d92d4912cbc
https://dev.to/_mertsimsek/using-xdebug-with-docker-2k8o
https://xdebug.org/docs/upgrade_guide