How To Run Xdebug Using PHPStorm in Docker

Errors are inevitable while developing software applications. If left unattended, these errors can have critical consequences on users and developers. In 2020, a study commissioned by the Consortium for Information & Software Quality (CISQ) concluded that software errors cost US organizations about $2.08 trillion.

To eliminate these costs, software professionals should never overlook testing & debugging. During and post-production, they can run an automated test suite to ensure that their products are free of errors & work as anticipated.

Likewise, in Dockers, you have to run commands to create & manage containers & run a complex application to test & carry out the debugging process. 

But as said, every path has its puddle; Docker also has complexity while managing the project configurations with all the dependencies. Earlier debugging applications from your IDE was straightforward in a typical local development environment. But now, Xdebug requires some additional configuration mechanisms.

To help you out, this blog will take you step-by-step through the installation and configuration process of Xdebug in PHPStorm with a Dockerized Symfony 4 application.

Pre-requisites-

• It was tested on an Ubuntu 18.04 machine with PHPStorm 2018.1.4 and the latest versions of Docker and Docker Compose. Few things might work a little differently in other operating systems.
• Have a basic understanding of Docker, PHP, and XDebug.
• You can clone this repository as a base to follow this guide as it contains a basic Symfony Flex application with all the Docker stuff explained in this article.

Step 1 - Dockerize the Application

Install Xdebug on your Docker container. The way to do this will depend on your base image. I always use alpine-based images. Refer to this  Dockerfile to know how you can dockerize a Symfony application, as included in the demo repository.

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

ARG WITH_XDEBUG=false




RUN if [ $WITH_XDEBUG = "true" ] ; then \

            pecl install xdebug; \

            docker-php-ext-enable xdebug; \

            echo "error_reporting = E_ALL" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \

            echo "display_startup_errors = On" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \

            echo "display_errors = On" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \

            echo "xdebug.remote_enable=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \

        fi ;

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

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

version: "3"

services:

  php:

    build:

      context: .

      args:

        - WITH_XDEBUG=true

    env_file: .env

    volumes:

      - .:/var/www/app:rw

Learn more on the complete docker-compose file.

The essential bit is the "env_file" instruction which tells Compose to load environment variables from a ".env" file. It is the standard way for Symfony 4 applications.

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

Environment Variables

We will define the following environment variables-

• PHP_IDE_CONFIG - This variable defines the server configuration associated with the application. More on this later.
• XDEBUG_CONFIG - This variable defines a few 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 to for incoming Xdebug connections. These two settings allow PHPStorm and Xdebug to communicate effectively. 

Note- It is mandatory to enable these two settings to facilitate its working.

We will add them to our ".env" file like this-

And that's it in terms of code.

Next, let's dig into PHPStorm configurations.

Step 2 - 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 same port that you configured previously in the "XDEBUG_CONFIG" environment variable.

Next, we need to configure a server. That 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

1. 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."
2. The "host" and "port" will enable your access to the application. In my case, it is localhost:8888.
3. And then the "Path mappings."
4. In the "Project files" section, you have to map the root path of your application to the path inside the container. In my case it's "/var/www/app".
5. Click "Apply" to save your configurations.
6. The last part is to configure the remote debugger of your project.
7. On the top right, click on "edit configurations":

         Now configure it like this:

Make sure you associate it with the previously created "server" definition. Use "PHPSTORM" as the IDE key to configure it appropriately. 

Once it is set, we can move to the testing.

Step 3 - Testing

• Open "src/Controllers/HelloController.php" and place a breakpoint in the "hello" method.
• Start your Docker container with docker-compose up.
• Then click on the "Start Listening for PHP Debug connections" icon on the top right corner of PHPStorm.

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

If you have followed the steps carefully, you will see the execution stop at your breakpoint.

And that's it. You have a fully configured development environment now with Docker and Xdebug integrated with PHPStorm IDE.

Happy debugging :)