Elephant standing on laptop
Development Stepping through problems (4 mins read)

By Christopher Crawford, Published on Nov 15, 2020

Typical Debugging

A lot of PHP developers will be used to debugging in the form of something like dd($data) logger($data) var_dump($data) echo $data etc... I used to do this as well before I realised the benefits I could gain personally from utilising a debugging tool. The ability to step through code one line at a ime when trying to fix a problem or even just learning a new code base is invaluable.

When I switched to using Docker for professional and personal development I found that trying to setup xdebug to work in both a testing setup and a incoming request setup to be very fiddly, so I tried multiple ways of setting this up and have been using it the same way successfully ever since.

I use PHPStorm as my IDE of choice and this setup will be tailored to it in particular, however the actual Dockerfile setup can be used anywhere. This post will be covering setting it up using Ubuntu 20.04, PHPStorm 2020.2 and a pre-existing Laravel Project.

The Docker Setup

Typically the way I like to work is to have a docker-compose folder in my project root with any configs I need to be nested inside of there such as nginx, mysql etc..

As of writing this post I am pulling from the php:7.4-fpm image which can be found here. I wont be covering setting up a Dockerfile as a whole as thats not the aim here, simply to get xdebug up and running.

You will want to ensure you have Pecl up and running and in your Dockerfile include the following snippet

RUN pecl install xdebug && docker-php-ext-enable xdebug

* Some of these extensions you may not need, they are required 
* as I am working with a Laravel application.
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd 

It is usually a good idea to keep your xdebug setting in a separate ini file and then copy it across during the build process, in my docker-compose folder within the project root I have a xdebug.ini file.


Your container ip address may be different from the one seen here and you can find yours with ifconfig and replace if needed.

If you are running an instance of PHP on your local machine outside of the container environment, you may have clashes with the port number as typically FPM will run on 9000, if thats the case you may want to switch to something like 9001 or 9002.

Now all we need to do is make sure a copy of our ini is pulled across during the build process.

// Copy our config from the local -> to the container location
COPY ./docker-compose/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

The PHPStorm Setup

Firstly lets setup our server. Go to Settings -> PHP -> Servers. Click the + icon to add a new server, provide a name of your choosing. Set the host to localhost, the port to 80 and the debugger to Xdebug. Now select Use Path Mappings. Dependant if you have any custom path setup on your container, this may vary however in my case I can set the absolute path on the server to /var/www

Next, go to PHP and ensure that the Debug port is set to the same value you set in the setup. Firstly, lets seup our remote debuggoing config, click on your configuration dropdown like so and select Edit Configurations.

This will provide a dialog where you can select the + icon and PHP Remote Debug, from there you can set it up like seen here. Important note: The IDE key(sessionid): field has to be the same as the key from the Dockerfiles xdebug.idekey

Now go to PHP -> Debug and change the debug port to the value you provided in the setup., then head over to DBGp Proxy and provide the value you set in the xdebug.idekey field into the IDE Key input, the port should be the same as the previous screen, click apply and close.

Open your PHPStorm config dropdown like so.

PHPStorm Configuration Dropdown

PHPStorm Configuration Dropdown

Choose Edit Configurations and then the + icon to make a new PHP Remote Debug that should look similar to mine.

Docker Remote Debug Setup

Docker Remote Debug Setup

Finally go to Settings -> PHP.

Look at the CLI Interpreter dropdown option, if this is blank then click the ... next to it and a dialog will appear.

As we are using a remote(Docker) interpreter, we have to set PHPStorm up in such a way that it can understand this and work with it.

  1. Click the + icon in the top left corner
  2. Select From Docker, Vagrant, VM, WSL, Remote...
  3. Select Docker
  4. Select the server we created earlier
  5. It should populate the correct PHP container in the Image Name field
  6. Click Ok

Check to ensure the details are correct and that a debugger is being shown as installed.

Completed Setup

Completed Setup

Now you should be able to listen forincoming connections and stop on them, as an example I set a breakpoint on the default welcome route in a Laravel application and we can now step through code as needed!

Stopped on a breakpoint from an external request

Stopped on a breakpoint from an external request