XDebug 3 and Docker Reference

README.md

XDEBUG 3 Configuration with Docker and PhpStorm

XDebug 3 only started working out of the box with PhpStorm version 2020.3

Reference article - Configure Xdebug

The list of changes from XDebug 2 to 3 are available here for reference - Upgrade Guide

Configuring PhpStorm

Go to PhpStorm -> Settings -> Languages & Frameworks -> PHP -> Servers

1. Click "+"
2. Name docker-cli (Same as serverName under PHP_IDE_CONFIG environment variable)
3. Host _
4. Default 80
5. Debugger Xdebug
6. Check the checkbox next to "Use path mappings"
7. Modify the absolute path on the server to /var/www/html

Running the CLI Command

1. Add breakpoints file
2. In PhpStorm click the icon to "Start Listening for PHP Debug connections"
3. Run in the docker file - docker-compose run php-container php test.php

Troubleshooting

1. Check firewall or selinux if on linux
2. The configuration host.docker.internal only became available under Mac and Windows with Docker version 20.04

docker-compose.yaml

version: '3.8'

services:
    php-container:
        build:
            context: .
            dockerfile: ./docker/Dockerfile
        volumes:
            - .:/var/www/html
            - ./docker/xdebug.ini:/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
            - ./docker/php.ini:/usr/local/etc/php/conf.d/custom.ini
        environment:
            PHP_IDE_CONFIG: "serverName=docker-cli"

Dockerfile

FROM php:7.4-cli-alpine

# Install xdebug
RUN apk add --no-cache --virtual .phpize-deps $PHPIZE_DEPS \
  && pecl install xdebug \
  && docker-php-ext-enable xdebug \
  && apk del .phpize-deps

WORKDIR /var/www/html

xdebug.ini

[XDebug]
zend_extension=xdebug.so

xdebug.mode = debug
xdebug.start_with_request=yes

#Replace host.docker.internal to your computers IP address if linux
xdebug.client_host=host.docker.internal