21 Feb 2018

• Xdebug Php Docker
• Phpstorm Docker Xdebug Not Working

Introduction

Languages & Frameworks - PHP - Debug - Xdebug - Can accept external connections; Languages & Frameworks - PHP - Debug - DBGp Proxy - Port 9000; Once this is done find Listen for debugger connections icon in PhpStorm in the toolbar and click it. If you want to call it from a command line remember to include XDEBUGSESSION cookie, i.e.

Setting up debugging tools in a docker environment is rarely as easy as it should. Here is a short tutorial to get it done in PHP with the Xdebug extension. If you are in a hurry you can quickly get all files used in this tutorial from this github repository.

• MediaRange Patrone Canon CLI-551M XL mit Chip magenta: MediaRange: 3,95: C235098: 3 Year Extended Warranty (Renewal or High Volume) APC: 124,30: C166237: IIYAMA 80.0cm (31,5') TF3237MSC-B1AG 16:9 M-Touch DVI+HD: Iiyama: 1.484,69: C299266: DURABLE Blanko-Register PP 10tlg farbig Verlauf grau: Durable: 5,09: C148200: Gigaset PRO N510 IP DECT.
• It is possible to run PHP cli without a docker-compose file, I have found it is easier to set up PhpStorm using this intermediate step. PhpStorm has several preconfigured Docker containers, source: Github - JetBrains / phpstorm-docker-images; Docker hub - PhpStorm; They can be used as follows: Php 7.3 CLI and XDebug 2.7.
• For this you need to create a new PHP CLI interpreter configuration: in your PhpStorm Settings go to Languages and Frameworks PHP and click the ‘’ button near the “CLI Interpreter” field. In new window add a new interpreter “From Docker, Vagrant, VM, Remote” choose “Docker Compose” radiobutton.

Setting up the php application running on docker

A prerequisite to this tutorial is to have a PHP application running on docker. If it's already set up feel free to skip this section. For the sake of simplicity I will place all files directly in the project root directory. Obviously I would advise against this and you should rather tidy things up in a folder containing all docker related files.

This recipe will contain:

Xdebug Php Docker

• A docker-compose.yml file for our web server running php along with nginx:

• The corresponding Dockerfile

I named it Dockerfile-php-app to make it explicit it's for the PHP image and not the nginx one.

• Along with a php.ini file

Its content does not matter at the moment but the file is required as we will need to append the Xdebug configuration later on.

• Then the nginx configuration to render our php

The file name is app.conf as referenced in the docker-compose file.

• Finally a dummy index.php file with a few instructions will do:

Run docker-compose up -d and browse http://localhost:8080/. You should be good to go.

Setting up Xdebug with vscode

The first thing we need to do is to update our docker image to include Xdebug. Let's add these 3 lines to Dockerfile-php-app:

Then let's touch our php.ini file by appending the xdebug configuration:

Run docker-compose build to get the latest version of your image.

Set the remote host to whatever your internal network IP is. On my ubuntu laptop, running hostname -I | awk '{print $1}' on the command line prints it.

Run docker-compose up -d a second time.

Phpstorm Docker Xdebug Not Working

Last but not least, you will have to update your vscode configuration. First install the PHP Debug extension by Felix Becker. Then in vscode select the debug tab, then click Add Configuration.. and select the PHP environment. This will open the launch.json file. Erase its content with the following:

Add a breakpoint in index.php and hit Listen for XDebug. Browse http://localhost:8080/. Vscode should pop and the code will be at your breakpoint! Make sure vscode is opened for the directory containing all these files but not a parent directory. Else the relative path will be wrong and vscode won't budge.

Known issues

According to the Xdebug documentation, Xdebug will still not start a debugging session automatically when a script is run. I did not myself experience any issue. A good way to test is to launch the debugger, then run the following:

If nothing happens, update the php_app service in the docker-compose.yml file by adding an environment variable:

Run these commands once again to check if everything is fine:

Multiple PHP containers

What if your application is composed of multiple PHP backends? In this case you will need to have them running in other docker containers, and the xdebug port (9099 for now) will conflict. A solution to this problem is to make good use of the Dockerfile ARG instruction.

This is what you get with 2 different php docker images and 2 docker-compose service accordingly:

• Here is the docker-compose.yml file

With the following instructions in Dockerfile-php-app, running docker-compose build will result in different docker images with different Xdebug ports.

Eventually, for each of your codebase, change the value of the port in your vscode debugger configuration:

If you found this tutorial helpful, star this repo as a thank you! ⭐

Related Posts