Running Xdebug In Docker Container

In this tutorial we're going to setup a docker container that will have xdebug installed into it so that we can run PHPUnit with xdebug enabled without having to installed it locally.

#Why would we want to do this?

This comes down to the way you work, someone people like to always have xdebug enabled so that they can step through their code in real time.

The way I work is that I prefer to have xdebug turned off and only have it enabled when I want to use it. I do this mainly for speed, I like to be able to run phpunit in the command line at any time and get a quick response back on the status of the application. If I had xdebug on it massively increases the time the tests take to run.

I like to use xdebug mainly on my tests, I tend to work in a TTD approach and if my tests aren't working I want to be able to step through the test code to see what's going on and why the tests are failing. Therefore I like to have xdebug turned off by default then enabled when I want to step through the failing tests.

The best way for this to work with me is to not install xdebug locally but to have a docker container with xdebug enabled and use this to run my debug tests through PHPStorm.

#How to setup a docker container with Xdebug?

I've already done this part for you go to Github and clone the repository PHP-Xdebug.

This repository has a simple Dockerfile that installs PHP 7.3 with a few development dependencies and Xdebug.

FROM php:7.3-cli-alpine

RUN set -ex \
    && apk update \
    && apk add --no-cache git mysql-client curl openssh-client icu libpng freetype libzip \
       libjpeg-turbo postgresql-dev libffi-dev libsodium \
    && apk add --no-cache --virtual build-dependencies icu-dev libxml2-dev freetype-dev libzip-dev libpng-dev \
        libjpeg-turbo-dev g++ make autoconf libsodium-dev\
    && mkdir /src && cd /src && git clone https://github.com/xdebug/xdebug.git \
    && cd xdebug \
    && sh ./rebuild.sh \
    && docker-php-source extract \
    && docker-php-ext-enable xdebug\
    && docker-php-source delete \
    && cd  / && rm -fr /src \
    && apk del build-dependencies \
    && rm -rf /tmp/*

USER www-data
WORKDIR /var/www

When this is cloned locally you can now use this in your PHPStorm IDE.

#PHPStorm Setup

First you need to setup a remote interpreter for your docker container, you do this by going to Preferences -> Languages & Frameworks -> PHP there's an option for CLI Interpreter where you can click on the ... menu and add a new remote interpreter.

Next under the Test Frameworks you can add the a new PHPUnit from remote interpreter, select your docker interpreter. Add a volume for your project into the /opt/project/ path, then select composer via autoload at location /opt/project/vendor/autoload.php.

Then you can setup the config options

• xdebug.remote_host - Local IP address
• xdebug.remote_port - Port defined in PHP debug settings
• xdebug.remote_enable - 1

Under the debug section Preferences -> Languages & frameworks -> PHP -> Debug. Make sure Xdebug port is set to the same as above.

Go to Preferences -> Languages & frameworks -> PHP -> Test Frameworks to configure PHPUnit. Add a new configuration type, select PHPUnit by remote interepter, select the docker container. PHPStorm will now use this container when running tests.

Then click the debug button at the top right to debug your tests. That's it, now you can run your unit tests in debug mode through PHPStorm and you'll be able to step through your code.

#Troubleshooting xdebug

You can turn on xdebug log to investigate any errors by outputting to a debug log by using the configuration settings xdebug.remote_log=debug.log.