Debug PHP in Docker with PhpStorm and Xdebug

Xdebug is one of the most known PHP extensions, a very complete and powerful debugger. This tutorial will show you how to use it in combination with PhpStorm, probably the most used PHP IDE; and Docker, the archi-known contanerization software.
This would allow us to simply write a Dockerfile with all the Xdebug configuration, and being able to easily deploy our Xdebug server anywhere.

For this tutorial, Linux Mint 18, Docker 1.12.3 and PhpStorm 2016.3.2 have been used.

You may skip environment installation and jump directly to the beginning of the tutorial below.

1. Installation

1.1. Docker

Note: Docker requires a 64-bit system with a kernel version equal or higher to 3.10.

We can install Docker simply via apt-get, without the need of adding any repository, just installing the package:

sudo apt-get update
sudo apt-get install

For more details, you can follow the Install Docker on Ubuntu Tutorial.

1.2. PhpStorm

We can download PhpStorm from JetBrains official site. Unfortunately, PhpStorm is not free, but it comes with an evaluation key for a 30 day free trial.

After downloading the tar.gz file, the only thing we have to do is uncompress it, place the folder in the directory we want to have PhpStorm (e.g., in $HOME), and execute the bin/ file.

The first thing is to select whether to import settings from previous PhpStorm versions or not, as shown in the image below.

1. Importing (or not) settings from previous PhpStorm versions.

In the next screen, we must choose the “Evaluate for free” option (only just if we don’t have a license, of course).

2. Choosing PhpStorm license.

After agreeing the terms of use of PhpStorm, the setup ends with the initial configuration screen. The most important option here is “Create desktop entry (integrate in system menu)”, for being able to start PhpStorm from the menu, instead of having to execute the script as made before.

3. PhpStorm initial configuration.


2. Creating the PhpStorm project

Before starting with the Docker container, we should first create the PhpStorm project, because for the container creation we will need the path to it.

Creating a project is as simple as opening PhpStorm and selecting “Create new project”. We will have to choose the PHP version (the same as the one running within the container), and the location for the project.

4. Creating the PhpStorm project.

3. Creating the PHP container

For creating the container, we will create a Dockerfile based on the official PHP image, in combination with Apache as web server; and installing and enabling Xdebug. Such Dockerfile will consist on:


FROM php:7.0-apache
ENV DEBIAN_FRONTEND=noninteractive
RUN pecl install xdebug
RUN docker-php-ext-enable xdebug
RUN echo "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20151012/" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_autostart=true" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_handler=dbgp" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_mode=req" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_port=10000" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_log=/var/log/xdebug_remote.log" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.idekey=PHPSTORM" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
RUN echo "xdebug.remote_connect_back=Off" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

The docker-php-ext-enable xdebug creates the config file for Xdebug; then, we throw the configuration for it to the file where is created. Note that we chose the port 10000 for Xdebug, and PHPSTORM for IDE key..

We can build the image just running.

docker build --tag=myphp . # Path to the Dockerfile.

For creating the container, we need the IP address of the host, since Xdebug needs the remote host IP, which will be passed to the container as environmental variable. In my case, the IP address is

As said before, we also need the path of the project in the host, in order to map with the web directory in the container.

Taking all this into account, we would create the container executing:

docker run -p 8080:80 -d --name=myphp1 -e XDEBUG_CONFIG="remote_host=" -v /home/julen/PhpstormProjects/phpstorm-docker-xdebug:/var/www/html  myphp

Note that we have mapped container’s port 80 to host’s 8080, to avoid conflicts in the case of having some web server running in the host.

Now, we should be able to access the web server running in the container with the URL http://localhost:8080/ (even if we get a 403 error).

4. Configuring access to Xdebug to PhpStorm

The next step is to make PhpStorm know how to use Xdebug.

For that, we have to click in the arrow placed in the right-top corner of the IDE, and select “Edit Configurations”.

5. Editing the run configuration.

In the new window, we have to click the green arrow, and select “PHP Remote Debug”.

6. Adding a remote debug configuration.

Now, we have to create a new server, clicking in the three dots in the “Servers” section. Here we have to set a name, the host the server is running (the container in localhost), and the port (8080, the exposed port to the host). We also have to set the web path of the server, which is /var/www/html.

7. Configuring the remote debug server.

Having the server configured, we just have to select it in the debug configuration, and specify the IDE key set in the Dockerfile for the Xdebug configuration, PHPSTORM:

8. Selecting the remote debug server.

Finally, now in “File/Settings/Languages & Frameworks/PHP/Debug”, in the “Xdebug” section, we have to specify the port we set in the configuration, and mark all the options.

9. Configuring Xdebug.

Once saved everything, we can start the debugging (Shift + F9) with the specified config. In the bottom part, in the “Debugger” tab, we will see the following message:

Waiting  for incoming connection with ide key ‘PHPSTORM’

Meaning this, that we are ready to start debugging.

5. Debugging the PHP code

For debugging, we can create a script as simple as the following:



$var = 5;


echo 'example.php'

And adding a breakpoint, for example, for the echo 'example.php'; statement, clicking left to it, outside the text editor. A read breakpoint will appear.

If now, we execute the script accessing it from the web server, entering the http://localhost:8080/example.php URL in the browser, we will see that some variables will appear:

10. Inspecting variables in the debugger.

As we can see, the debugger shows both PHP built-in variables, and the variables we have declared in our script. In this case, in the current breakpoint, shows that the variable value is 6, since we have incremented it in the previous statement.

6. Summary

This tutorial has shown how to easily have a complete PHP development environment with Xdebug thanks to Docker, just defining a Dockerfile with the configuration for Xdebug and creating a container; and then configuring the PhpStorm IDE to make use of it.

Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

1 Comment
Newest Most Voted
Inline Feedbacks
View all comments
5 years ago

Thanks, Jule, for this easy-to-follow recipe!

It worked nicely.

One thing some might consider: Incoming port 10000 may not be open but restricted by a firewall, so open it first (which I had to do).

Best regards,

Back to top button