Docker Phpstorm Xdebug

Posted : admin On 1/29/2022

Add Xdebug to the Webserver Dockerfile Since this image is using alpine, it's a little different than a lot of the approaches you might find if you just google 'Install Xdebug PHP.' At the end of your app Dockerfile you need to manually install xdebug using pecl, so add this command at the bottom.

This post was cross posted on
  • On the Windows side, I have installed PHPStorm. XDebug Remote Debugging. So the idea is to write PHP code in PHPStorm on Windows and run and debug PHP code on Ubuntu over WSL2. To do that, we need to setup remote debugging for XDebug so that PHPStorm can connect to it and set breakpoints, show variable values and step through the code.
  • PHPSTORM + XDEBUG (2/3) + WSL2 + DOCKER. Small example project to show how to configure xdebug (2 or 3) with WSL2 and Docker. This solution works only if you use PhpStorm on WSL2 with X server! WSL2 change Linux IP every reboot time, so you should, add global variable (WSLIP) in your Linux system.

Docker has changed dramatically the way we develop applications. Thanks to it, it is really easy for everyone to run a complex application with a single command, without having to worry about the inner details like dependencies. These advantages are even greater when working on a team or enterprise context. I still remember being like the first 3 days when I joined my current company, configuring the project and all the related libraries and tools. Docker make it such much easier, faster and consistent.

But everything comes with a price. There is an extra complexity of maintaining all the Docker stuff. Also some things that were very easy in a normal development environment running locally, like debugging your application from your IDE, now requires some extra configuration. And in case of getting Xdebug to work, its not an easy task. I couldn't find a single guide that have all the steps from start to finish. Thats why I decided to write this article. It will guide you to step by step through the process of installing and configuring Xdebug and PHPStorm with a Dockerized Symfony 4 application.


  • This was tested on an Ubuntu 18.04 machine with PHPStorm 2018.1.4 and latest versions of Docker and Docker Compose. Some things might work a little different in other Operating Systems.
  • I assume you have a basic Knowledge of Docker, PHP and XDebug.
  • You can clone this repository as base to follow this gude as it contains a basic Symfony Flex application with all the Docker stuff explained in this article included.

Step 1 - Dockerize the application

Of course, to be able to use Xdebug you must install it on your Docker container.The way to do this, will depend of your base image. I always use alpine based images. I wont enter in detail about how to Dockerize a Symfony application. You can follow along with the Dockerfile included in the demo repository.

Here is the relevant excerpt of the Dockerfile that installs Xdebug:

I dont want have to have a separate Dockerfile for development and production, so I have defined a build argument that will tell whether we want to install Xdebug or not.

Then, on my Docker-compose file I have the following definition for my application:

See for the full docker-compose file.

Nothing really fancy about this. The important bit is the 'env_file' instruction which tells Compose to load environment variables from a '.env' file, which is the standard way for Symfony 4 applications.

We will use that file to add some required environment variables for Xdebug. If you prefer in you can also add directly to the docker-compose file using the 'environment' section.

Environment Variables

We will define the following environment variables:

Phpstorm Docker Xdebug Not Working

  • PHP_IDE_CONFIG - This variable defines the server configuration associated with the application. More on this later.
  • XDEBUG_CONFIG - This variable allows to define some Xdebug configurations. The 'remote host' is the private ip of your host machine (the one your PHPStorm is running). The 'remote_port' is the port that PHPStorm will be listening for incoming Xdebug connections. These two settings allow PHPStorm and Xdebug to communicate. It wont work without this.

We will add them to our '.env' file like this:

And thats it in terms of code.

Next lets dig into PHPStorm configurations.

PHPStorm configurations

The first thing you should do is to check your Debug settings. In PHPStorm, go to File -> Settings -> Languages and Frameworks -> PHP > Debug.

Make sure you have the some port that you have configured previously in 'XDEBUG_CONFIG' environment variable:

Next, we need to configure a server. This is how PHPStorm will map the file paths in your local system to the ones in your container.

Go to File -> Settings -> Languages and Frameworks -> PHP -> Servers

Give a name to your server. It should match the value you have defined in your 'PHP_IDE_CONFIG' environment variable. We will call it 'symfony-demo'.

The 'host' and 'port' is how will access your application. In my case is localhost:8888.

And then the 'Path mappings'.

In the 'Project files' section you have to map the root path of your application to the path inside the container. In my case its '/var/www/app'.

Click 'Apply' to save your configurations.

The last part is to configure the remote debugger of your project.

On the top right, click on 'edit configurations':

Click in the green 'plus' sign at the top left and select 'PHP Remote Debug' from the list.

Now configure it like this:

Make sure you associate it with the previously created 'server' definition. Use 'PHPSTORM' as idekey.

Your IDE should be now correctly configured. Lets test.


  • Open 'src/Controllers/HelloController.php' and place a breakpoint in the 'hello' method.

  • Start your Docker container with docker-compose up

  • Then click on 'Start Listening for PHP Debug connections' icon on top right corner of PHPStorm.

  • Open http://localhost:8888?XDEBUG_SESSION_START=PHPSTORM

If everything went well you should see the execution stop at your breakpoint.

And thats it. You should now have a fully configured development environment with Docker and Xdebug integrated with PHPStorm IDE.

If you have any issues or questions feel free to comment bellow or in the GitHub Repository.

Thank you and good debugging ;)

July 26, 2018

To follow this tutorial, you must have the Xdebug extension installed on your container. In my example, I will use a Docker image of TheCodingMachine created by David NĂ©grier. If you are starting a project, I recommend you to download one of our images here TheCodingMachine Docker PHP images

My base docker-compose.yml file looks like this:

Note: the PHP_EXTENSION_XDEBUG environment variable is specific to the thecodingmachine/php. It automatically configures Xdebug for the container.

Ports configuration

Keep in mind that PHPStorm opens port 9000 (by default) so Xdebug can connect to it. Our PHP container has Xdebug installed and Xdebug will try to connect to PHPStorm on port 9000 by default.

Out of the box, everything should be fine...

... except if port 9000 is already taken by another program on your host (your machine running PHPStorm).

Switching port

Port 9000 can be already used. In particular, if you are using PHP-FPM, the default port for PHP-FPM is 9000.This directly conflicts with the XDebug port.

If you want to use another port for Xdebug, follow the instructions below.

I recommend to use port 10000 instead.

Otherwise, just keep the default configuration port.

Registering your container server in PHPStorm

First, click on edit configurations, on the top right of PHPStorm window.

Then, follow the explanation in picture. All numbers are explained below.

(1) Click on add button

(2) Confirm it by clicking on PHP Web Page

Docker Phpstorm Xdebug

(3) Define a name for your project

(4) Click on ... to add a debug server

(5) Once it's done, you are on debug server page. Click on '+' button to create a new one.

(6) Define a server name like docker_[your_project_name]

(7) Add your host on port 80 using Xdebug

(8) Don't forget to click on Use path mappings

(9) We need to add path mapping. Indeed, from the point of view of Xdebug, the PHP application runs in the '/var/www/html' (we are in a container!).But for PHPStorm, my project is in my host machine directory! So we need to map the root of your PHP application to the '/var/www/html' directory, as shown on the image above.

At this point, you should be able to put a breakpoint in your code, start a debugging session and get the application to stop on the breakpoint. Jump to chapter 'Run Xdebug' to see how to use Xdebug.

Xdebug CLI

All applications are not web-based. You might also want to debug a command-line application, from within your container.Let's see how to enable Xdebug for scripts (CLI)

In the docker-compose.yml, just add those environment variables

Remember that we are using our technical director's (David NĂ©grier) images. That's why we can set PHP extensions, PHP .ini configurations into the docker-compose.yml.For more details, please look at this TheCodingMachine Docker PHP images.

(1) Enable the Xdebug extension

(2) If you are using a different Xdebug port, set your custom Xdebug port

(3) Add your Xdebug server name

(4) If you are using the default Xdebug port, please remove remote_port=[your_xdebug_port]. Otherwise, add your custom Xdebug port

Run Xdebug


Place a breakpoint in your code and launch a debug session

A new windows should open and you should access to PHPStorm debug bar.

Scripts (CLI)

Click on Start Listening for PHP Debug connections

The button should appear like this :

Place a breakpoint in your code.

Now, just go into your php-apache container using docker exec -ti [container_id] bash and run your script manually.

Addentum: Installing Docker integration in PHPStorm

There is a very useful PHPStorm extension to quickly and efficiently manage your docker containers.

For example:

  • see the logs by container
  • have access to bash in a clique
  • quickly see environment variables
  • clear or restart containers

Before starting

  • You should check that the 'Docker integration' is enabled on your IDE
  • Start the Docker daemon on you machine
  • Move to your favorite Docker project in PHPStorm

Configuring Docker

Now everything should be good, just go to Preferences... > Languages and Frameworks > PHP

(1) Click on ... for openning the remote PHP interpreter

(2) Add a new CLI interpreter by clicking on From Docker, Vagrant, VM, Remote...

(3) Click on Docker (remember that you should start Docker daemon)

(4) Add a new server

(5) Select a server name

(6) Choose how to connect on Docker

(7) Make sure the connection is successful

(8) Select your favorite default image

Docker Phpstorm Xdebug Phpunit

(9) You need to set the path mapping for your code. By default, it's /opt/project in the container, just change it to /var/www/html

Done! Just click on the Docker button on the bottom of PHPStorm window.

About the author

Alexis is an experienced technical project manager who manages several projects including Eco-Emballages (CITEO). Graduate of EPITECH, Alexis is specialized in PHP frameworks (Symfony, Laravel, Mouf) and he masters Docker.

Related articles

Setting up a XDebug debugging environment for PHP / WAMP / Eclipse PDTJuly 8, 2010

Latest articles

Php Docker Xdebug Phpstorm

Releasing GraphQLite 4: GraphQL in PHP made easyJanuary 6, 2020
Getting started with TDBM 5.1 and SymfonyAugust 6, 2019

Open-source matters

At TheCodingMachine, we are using open-source tools daily to build our projects. And since we and our clients are ripping huge benefits from these open-source products, we also try to 'give back' to the open-source community.

Freelance Developer?

At TheCodingMachine, we are always looking for top freelance developers to work with us on our next state-of-the-art project.
Interested in developing quality projects? We love good work and we pay fairly.

We are hiring!

Living in France? We are actively looking for developers and project leaders in our Paris and Lyon office.

About us

At TheCodingMachine, we strive to develop websites , extranets, intranets and business web applications in PHP and JavaScript for a wide range of clients.
Do not hesitate to contact us!

Best practices

When writing code, we expect it to be of the best possible quality. To enforce this quality, we redacted our own 'best practices' described in a dedicated website.
We are happy to share those with you!


We are the happy parents of Packanalyst, a free online service that lets you search any possible PHP class or interface referenced on Packagist.
Pretty useful for open-source developer to keep an eye on who is using what class/interface of your packages.