Docker Php With Xdebug

Posted : admin On 1/29/2022

Running PHP and an Apache in a Docker container is very handy for local development. But how can we debug the PHP code running in the container? In this post, I show you how to configure Xdebug in a PHP container and configure IntelliJ IDEA Ultimate or PhpStorm for remote debugging.

Docker build -t php-xdebug-custom -f Dockerfile. Create docker-compose.yml file in 'docker' folder: Here I use 'php-xdebug-custom' image instead of 'php:7.2-fpm. FROM php:7.0-apache RUN a2enmod rewrite RUN docker-php-ext-install pdo pdomysql RUN apt-get install php-xdebug -y COPY php.ini /usr/local/etc/php/ COPY. /var/www/html/ When I'm running the same command in my computer, the XDebug is getting installed without any error: apt-get install php-xdebug Where might the problem be?

First of all, we need to install and activate Xdebug in our PHP container. Therefore, we create an own Docker image based on the PHP/Apache image. Within the Dockerfile we install and enable Xdebug using pecl and docker-php-ext-enable. Afterward, we have to configure Xdebug with some properties in the php.ini. Take a look at the following Dockerfile:

Docker Php Fpm Xdebug

This leads to the following php.ini file within the container:

Port 9000 is the default port and can be skipped. Using xdebug.remote_connect_back, we don’t have to configure the IP of our development machine (where PhpStorm and the Xdebug server runs) manually. If xdebug.remote_connect_back is enabled, Xdebug automatically detects the IP of the inital HTTP request which triggers the PHP execution and connects back to this IP. More details can be found in the xdebug documentation.

To start the container, we can use the following docker-compose.yml:

Create a Run Configuration of the type “PHP Remote Debug”. To be able to select this configuration, you may need to scroll down in the type selection popup (“Add New Configuration”) and click on “52 items more (irrelevant)” in order to find the type “PHP Remote Debug”.

Enter an arbitrary key for Ide key(session id). I usually choose something like IDEA_DEBUG. It’s only important that you remember this key because we will use it later for the request to trigger the debugging.

Click on the three dots ... next to the Servers field to create a new server.


Use the following server configuration:

  • Name: docker (or so)
  • Host: localhost
  • Port: 80
  • Debugger: Xdebug
  • Use path mappings: src -> /var/www/html. Hint: To submit the “absolute path on the server” press enter after typing the path in the text field. If you only click out of the field, your input will be removed.

Build and start the PHP container

Start the created Debug Configuration in PhpStorm.

Create the simple PHP file hello.php in the src folder with the following content:

Docker Php Xdebug Slow

Add a breakpoint and make a HTTP request to the PHP file. Don’t forget to append the query parameter XDEBUG_SESSION_START=IDEA_DEBUG to the URL.

Now, PhpStorm should stop at the breakpoint and you should be able to see the value of the variable $world and step through your PHP code.

  • In the above example, we triggered the debugging by passing the Xdebug key manually. But there are other means (like the Chrome extension Xdebug helper) available. Further information can be found here.
  • Does xdebug work at all in the container?
  • Install xdebug - just if you are curious.
  • ‘Configuring xdebug in IDEA’ provides additional information about the configuration.

Docker Php Xdebug Vscode

I used the described approach in my project comment-sidecar. Check it out for the complete source code.