Configuring Xdebug in PhpStorm

Debugging is one of the most important processes in programming. With the help of the debugger, you can see what is actually happening in the program, what functions are being executed, what is stored in variables, and also perform everything step by step and understand exactly on which line and at what values of variables the error occurs.

The PHP programming language uses the Xdebug debugger, and PhpStorm is one of the most popular development environments. In this article, we will look at how to configure Xdebug in PhpStorm for debugging on the local computer and in Docker.

  • Configuring Xdebug in PhpStorm
    • 1. Debugging on the local computer
    • 2. Debugging Php in Docker
  • Conclusions

Configuring Xdebug in PhpStorm

1. Debugging on the local computer

All the settings will be shown on the example of Ubuntu and the PHP interpreter configured with Apache. For other configurations, the file paths may differ, but the essence will remain the same. Let’s see how this will work. The Xdebug debugger allows you to pause code execution, view the call stack, and view the contents of variables. However, it does not have a convenient management interface. Therefore, we will use the IDE to manage debugging. But the IDE can’t tell the debugger in any way that it needs to start debugging, because it is only responsible for the code. To do this, you will also need the Debug Helper browser extension, with which you can enable debugging mode.

You must first install Xdebug. To do this, run:

sudo apt install xdebug

After completing the installation of Xdebug, you need to configure the program so that when you start a debugging session, it tries to connect to our IDE to manage debugging. To do this, add these lines to the file /etc/php/7.4/apache2/conf. d/20-xdebug. ini in version Xdebug 2:

sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini

For the new version of Xdebug 3, the old configuration will also work, but it is better to use the new standard:

xdebug.discover_client_host = false
xdebug.client_host =
xdebug.client_port = 9000

Let’s take a closer look at these settings. The first parameter of xdebug. mode – debug mode, possible options:

  • develop-enables output of additional information, overrides var_dump;
  • debug – the mode of line-by-line code execution, which is exactly what you need in this case;
  • profile-profiling;
  • trace-the trace of the program execution.

If necessary, you can enable multiple modes by separating them with commas. The second line of xdebug. start_with_request defines how the debugger will be started for the debug, trace, and similar modes:

  • yes – always, when running php scripts;
  • no-run only from code using special functions;
  • trigger – on request, using a special variable in $_ENV, $_POST, $COOKIE, or in another array. This option is best suited in this case so that the debugger does not run when it is not necessary.

If the third line of xdebug.discover_client_host is true, then xdebug tries to connect to the host passed in the HTTP_X_FORWARDED_FOR header. But since the host is specified in the next line, this feature is not needed in this case. Then the client host is specified, where it is necessary to connect to manage debugging and port 9000. This is the port that PhpStorm uses by default at the moment. After saving the settings, restart Apache:

sudo systemctl restart apache2

Now you need to configure PhpStorm. Run the program, then open the menu Run -> Edit Configurations>. You will see a window where you need to configure the debugger.

Click the + button and select PHP Remote Debugger from the list that opens:

In the settings, you can not change anything, just specify the name of this debugging method. If the server from which connections are expected is not set, then all connections will be accepted.

If you need to change the port to which Xdebug will connect, open the menu File -> Settings ->> PHP ->>> Debug ->>>> DBGp Proxy>>>>. Here you can specify the desired port:

Now the IDE is ready. Click on the bug icon on the top toolbar to start the program waiting for the debugger to connect and set a few breakpoints in the code by simply clicking in front of the line with the code:

Then it remains to configure the browser. For Chrome, you can download this extension. Install it and open the page you want to debug. Click on the extension icon and select Debug. The extension icon will turn green:

Refresh the page and return to PhpStorm. If everything was done correctly, a debugging session will start there. When you first start the program, you may be asked to configure the correspondence of local file paths with remote ones. For the local server, you do not need to configure anything here, just click Accept:

Then the debugger will stop execution at the selected breakpoint and the debug interface will appear in the program:

As you can see, everything is quite simple. Next, let’s figure out how to configure Xdebug PhpStorm and Docker.

2. Debugging Php in Docker

With Docker, there is one difficulty. Since the debugger must connect to the IDE itself, you need to push the host to the container. On windows, you can do this by using the host.docker.internal address. But in Linux, this does not happen by default. In order to add such an address, you need to add the following lines to docker-compose:

extra_hosts:   host.docker.internal: host-gateway

Let’s use this directory structure for this example:

The minimum required docker-compose.yaml will look like this:

version: '3.5' networks: losst-network: services: nginx: image: nginx ports: - '8094:80' volumes: - ./www/:/var/www/ - ./conf/nginx:/etc/nginx/conf.d networks: - losst-network php-fpm: build: context: ./conf/php-fpm extra_hosts: host.docker.internal: host-gateway volumes: - ./www:/var/www/ networks: - losst-network 

Here, two containers are declared, nginx and php-fpm. The first one does not need to make any changes, so you can just take the official image, mount the source folder, the configuration file, and forward the port. In the second container, you need to install and configure Xdebug, so you will have to build it based on the official php container. For the same container, you must specify the extra_hosts directive, without it, nothing will work. The Nginx configuration is also quite standard:

server { listen 80; server_name _ !default; root /var/www/; add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Content-Type-Options "nosniff"; index index.html index.htm index.php; charset utf-8; location / { try_files $uri $uri/ /index.php?$query_string; } error_page 404 /index.php; location ~ .php$ { fastcgi_pass php-fpm:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; include fastcgi_params; } } 

Here the processing of PHP scripts in the php-fpm container is configured, and the redirect of non-existent URLs to index.php, which is quite standard for many frameworks and CMS. The most interesting thing is the Dockerfile of the php-fpm container, it looks like this:

FROM php:8.0.3-fpm-buster
RUN pecl install xdebug
&& docker-php-ext-enable xdebug
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Here, you install xdebug using pecl, and then copy its configuration file to the container. Here is this configuration file:

xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

The container has Xdebug 3 installed for PHP 8, because the old version with this version of the language no longer works, so the new configuration syntax is used. Well, the host, host.docker. internal, which was previously registered in docker-compose.yaml. The configuration of xdebug PhpStorm docker is complete. Then you can start the project:

docker-compose up --build

Now, as in the previous version, you can enable debugging mode in the browser, refresh the page, and the debugger will successfully connect to the IDE, despite the fact that it works in Docker:


In this article, we looked at how to configure xdebug PhpStorm on the local computer and in the Docker container. If everything is done correctly, the debugger will work and help you look for errors in the code.


(Visited 115 times, 1 visits today)

Leave a Reply

Your email address will not be published. Required fields are marked *