How to debug your PHP app using Xdebug, Docker and PhpStorm

If you are a PHP developer, you've probably heard or even worked with Xdebug.?

For those of you that haven't heard of this amazing tool:?

Xdebug is an extension for?PHP, and provides a range of features to improve the PHP development experience.

As you may have guessed it, it's a tool used for debugging. If you are curious to know more about it, you can find lots of useful information on their website.?

PhpStorm is another great tool that makes our lives easier. It has all the featues you may wish for an IDE and it is built for smoother developer experience.?

Okay, enough talk, let's get to work, shall we?

In this article, I'm going to talk about how to debug your PHP application running in a Docker container while using PhpStorm.

Make sure you have the following things installed on your local: composer, Docker and PhpStorm.

For the purpose of this article, let's create a brand new Laravel application.

Open up a terminal and run:

composer create-project laravel/laravel xdebug-test        

Now that we have a brand new project to work with, let's open it in PhpStorm.

Just with this initial setup, you have a solid starting poing for developing an awesome web application. You can learn more on Laravel's documentation.

Okay, let's create some containers.

Usually, I start with an PHP and a nginx container.?

In your project's root directory, create a new directory called docker.

Inside it, create two directories: nginx and php.

Inside the nginx directory, create a new file called default.conf, where we will define a basic web server:

server {
    listen 80;
    server_name xdebug.test;
    client_max_body_size 100M;
    index index.php index.html;
    access_log /var/log/example-app.access.log main;
    root /var/www/html/public;
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php {
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param APPLICATION_ENV development;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}        

Create a Dockerfile in the same directory:

FROM nginx:1.13

COPY default.conf /etc/nginx/conf.d/default.conf        

Inside the php directory, let's craete a file called xdebug.ini where we will place some configuration needed to enable xdebug:

zend_extension=xdebug

[xdebug]
xdebug.mode=debug
debug.discover_client_host=true
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.idekey=PHPSTORM        

Also, let's create a Dockerfile inside the php directory and let's use this snippet:

FROM php:7.4-fpm

WORKDIR /var/www/html

RUN curl -sS https://getcomposer.org/installer | php \
    && mv composer.phar /usr/local/bin/composer

# Xdebug
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

COPY xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
        

We need composer inside our container to install our project's dependencies and we need to also install xdebug and enable it as a PHP extension, as well as copy the configuration we have prepared for it.

Finally, in the root directory of the project, create a file called docker-compose.yaml and paste the following snippet:

version: '3'

services:
    nginx:
      build:
          context: ./docker/nginx
      container_name: xdebug-test-nginx-container
      volumes:
          - ./:/var/www/html
      ports:
        - "80:80"
      links:
        - php
    php:
      build:
          context: ./docker/php
      container_name: xdebug-test-php-container
      volumes:
        - ./:/var/www/html        

That's it! Let's start our docker containers.

Make sure your Docker daemon is running and then open a terminal inside your project's root directory and run:

docker-compose build && docker-compose up -d        

This will build and start up the containers and you should see two containers running in a detached mode:

Open up your browser and navigate to your localhost:

You should see the Laravel welcome page.

Great! That means that our Docker containers are working.

Now lets tweak that index route a little bit.

Navigate to routes/web.php file and change the index route as follows:

Route::get('/', function () {
    $displayText = "hello, world";
    return $displayText;
});        

If you reload the page, you should see the hello, world text being displayed:

And now the fun part!

Let's hit a breakpoint on the following line:

And let's start listening for debug connections:

If you reload the page the following pop-up shows up:

Go ahead and click accept. This registers a new server for you in PhpStorm.

If you hit reload again, you expect the breakpoint to be triggered but nothing happens.

Why is that so?

Well each file/directory from our project that we intent do debug on our server (in this case running on a Docker container) must be mapped to an absolute path on the server - or in other words, we need to configure the path mappings.

Sounds scary? It's certainly not. Under Preferences | Settings, navigate to PHP > Servers.

You should see the server that was created by the pop-up just a minute ago:

Make sure you have the Use path mapping checkbox checked and then map the root directory of the project to the following path on the server and save those settings:

If you hit reload again, the debugger should work, but let's just do one more step.

Under Run select Edit configurations... :

Click to Add New Configuration:

Then select PHP Remote Debug:

Then create a configuration like this:

Under Name you can put anything you want.

Make sure to check the Filter debug connection by IDE key checkbox and under Server, to select the server we created earlier.

PHPSTORM is an IDE key that we defined earlier in our xdebug.ini configuration.

That's it! Now if you reload the page, the breakpoint should be triggered:

That's all you need to start debugging your application.

Congratulations if you have made this far!

I hope you find this article useful.

Feel free to reach out to me if you have any questions.