Yesterday Dmitri Goosens wrote about how to integrate Xdebug into almost any Docker Setup in PHPStorm. An article that I definitely need to digest a bit more as the PHPStorm integration is something that I often neglect. I am happy when it works on the CLI 😁

One thing though that Dmitri skips though (an dfor good reasons) is how to get Xdebug into your Docker environment.

As I have done that quite a number of times by now I thought I’d share the way I do it currently.

This is my Dockerfile

FROM php:8.3-rc-fpm
RUN PHPIZE_DEPS="autoconf \
      cmake \
      file \
      g++ \
      gcc \
      libc-dev \
      libpcre2-dev \
      make \
      git \
      pkgconf \
      re2c" \
    && XDEBUG_VERSION="" \
    && if [ "$(php -v | head -n 1 | grep 8.3)" != "" ]; then XDEBUG_VERSION="-3.3.0alpha3"; fi \
    && apt-get update \
    && apt-get install -y $PHPIZE_DEPS \
    && pecl install xdebug${XDEBUG_VERSION} \
    && docker-php-ext-enable xdebug \
    && echo "xdebug.mode=debug\nxdebug.discover_client_host=on\nxdebug.start_with_request=yes\nxdebug.log_level=0" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
    && apt-get remove -y $PHPIZE_DEPS

That should install a running version of Xdebug on whatever version of PHP you are using and even allows to use the soon to be relesased PHP8.3.

The main lines here are

    pecl install xdebug${XDEBUG_VERSION} \
    docker-php-ext-enable xdebug \

everything else is decoration resp. necessary that those two lines can do their magic.

Feel free to adapt the FROM line to whatever PHP-version you want to use from dockers official PHP-image (remember that that is not maintained by the PHP folks! It’s maintained by Docker!)

After a docker build -t phpxdebugtest . you should now be able to call docker run phpxdebugtest php -v and see this

PHP 8.3.0RC5 (cli) (built: Nov 1 2023 05:26:54) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0RC5, Copyright (c) Zend Technologies
with Xdebug v3.3.0alpha3, Copyright (c) 2002-2023, by Derick Rethans

And now have fun integrating that Xdebug enabled PHP-Container into your PHPStorm.