Xdebug in VSCode with Docker

In my last post, I talked about how to configure a development environment and how it extends a Dockerfile made for production.

Now, I would like to share how we can build upon our previous Dockerfile in such a way that Xdebug can run directly from Docker and also connect it with Visual Studio Code.

By choosing this approach, we substantially reduce the amount of setup that each team member has to do on their machine to get the project up and running, which means that we can start writing code faster.

So, why is this so important? Recent research from JetBrains shows that 62% of PHP developers debug their code using var_dump(), die(), dd(), and dump(). From my perspective, there is nothing wrong with that. Even if you do it by choice and not because you lack knowledge.

I'm included in the 62% of developers who debug their code with auxiliary functions instead of using a full-featured debug solution such as Xdebug. I'm a heavy Neovim user, and I didn't adapt quite well to using Neovim with Xdebug; it is just easier and faster to use my code snippets around the dd() function.

But occasionally, I catch myself in situations where it would be faster to jump into Visual Studio Code and just use Xdebug, especially when I'm working with other people who aren't familiar with Vim or Neovim.

Content

• XDebug config file
  • Explaining xdebug.ini
• Visual Studio Code
  • Explaining launch.json

Xdebug config file

Before jumping into VSCode, first we have to clear up a few things about Xdebug to fully grasp the changes we’re going to make to the IDE. The information was first introduced on the topic of the command directive in a previous post. You will notice that at some point a xdebug.ini file gets copied from a local .docker folder into /etc/php8/conf.d/50_xdebug.ini at the container.

Even though the content of the file got shown, I intentionally didn't explain its content so that we could explore the debugging topic all at once, going all the way from configuring Xdebug to using it with an IDE.

Down below, we have the same Xdebug config file from the previous post, placed at .docker/xdebug.ini on the root of our Laravel project. Each line of code will be explained further, but in case you want to know every configuration that you can add in this file, check the Xdebug documentation.

zend_extension=xdebug.so
xdebug.mode=develop,coverage,debug,profile
xdebug.idekey=docker
xdebug.start_with_request=yes
xdebug.log=/dev/stdout
xdebug.log_level=0
xdebug.client_port=9003
xdebug.client_host=<YOUR_COMPUTER_IP>

Explaining xdebug.ini

• zend_extension=xdebug.so

A Zend extension hooks into “lower-level” languages; a single extension can be both a PHP and a Zend extension; despite being very uncommon, it's possible, and Xdebug is a good example of it.

• xdebug.mode=develop,coverage,debug,profile

This setting controls which Xdebug features get enabled; according to the documentation, the following values will get accepted:

- develop
    Enables Development Helpers, including the overloaded var_dump().
- coverage
    Enables Code Coverage Analysis to generate code coverage reports, mainly with PHPUnit.
- debug
    Enables step-debugging. This can be used to step through your code while it is running and analyze the values of variables.
- profile
    Enables Profiling, with which you can analyze performance bottlenecks with tools like CacheGrind.

• xdebug.idekey=docker

Controls which IDE key Xdebug should pass on to the debugging client or proxy. The IDE Key is only important for use with the DBGp Proxy Tool, although some IDEs are incorrectly picky as to what its value is. The default is based on the DBGP_IDEKEY environment setting. If it is not present, the default falls back to an empty string.

• xdebug.start_with_request=yes

The functionality starts when the PHP request starts and before any PHP code is executed. For example, xdebug.mode=trace and xdebug.start_with_request=yes, start a function trace for the whole request.

• xdebug.log=/dev/stdout

Configure Xdebug's log file, but in this case, we are redirecting the log content to the default stdout of our container.

In case you don't want to see these logs you can comment out this line of your .docker/xdebug.ini file by changing the line to ;xdebug.log=/dev/stdout.

• xdebug.log_level=0

Configures which logging messages should be added to the log file. In this case, we are instructing Xdebug to log only errors in the configuration. If you want to see more information, you can use level 7 for log info or level 10 for log debug.

• xdebug.client_port=9003

The port to which Xdebug tries to connect on the remote host. Port 9003 is the default for both Xdebug and the Command Line Debug Client. As many clients use this port number, it is best to leave this setting unchanged.

• xdebug.client_host=<YOUR_COMPUTER_IP>

Configures the IP address or hostname to which Xdebug will attempt to connect when initiating a debugging connection. This address should be the address of the machine where your IDE or debugging client is listening for incoming debugging connections.

Down below, you can see how to get your IP address correctly in the main OS the developers use. In case you are using a different OS, the commands may serve as a base to try to extrapolate a solution for your use case.

macOS:

ipconfig getifaddr en0

Windows with WSL:

grep nameserver /etc/resolv.conf | cut -d ' ' -f2

Linux (Debian-based distros):

hostname -I | cut -d ' ' -f1

Once you have correctly found your IP address, you can place it into xdebug.client_host as mentioned before, and that will leave you with a directive looking similar to this: xdebug.client_host=192.168.0.158.

In summary, you've instructed Xdebug to start with a request and try to send the debug events to the host with the IP 192.168.0.158 on port 9003. Since the IP represents your computer, when configuring Visual Studio Code to connect to Xdebug, the configuration will be extremely similar to when connecting to localhost.

Visual Studio Code

As you may already know, Visual Studio Code, or, VSCode for short, is a source-code editor made by Microsoft for Windows, Linux, and macOS. Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git.

With that being said, you may be wondering: “What do we need to have VSCode with all the aspects of an IDE with full-featured debugging?”

For starters, we will need to install the PHP Debug official plugin:

Thereafter, a file called launch.json has to be generated; this file gets used by the debugger in any language, which means that a part of this process can be reused when configuring the debugger on VSCode for other languages.

You can generate the file by clicking in Run and Debug > Create a launch.json file > PHP, as the following screenshot shows:

Finally, the launch.json file will be created with a specification of version and a configurations array with three configurations: Listen for Xdebug, Launch currently open script and Launch Built-in web server, as the screenshot shows:

Now, to properly configure the launch.json file, you have to replace the configurations array by the following:

{

    "version": "0.2.0",

    "configurations": [

        {

            "name": "Listen for XDebug on Docker",

            "type": "php",

            "request": "launch",

            "port": 9003,

            "pathMappings": {

                "/var/www/html/": "${workspaceFolder}"

            }

        }

    ]

}

Explaining launch.json

• name

Indicates the name given to a configuration object.

• type

Indicates the underlying debugger is being used.

• request

Indicates whether the configuration is intended to launch the program or attach to an already running instance.

• port

Indicates the port on which to listen for Xdebug

• pathMappings

Indicates a mapping of server paths to local paths.

When using /var/www/html/ as key, VSCode knows that the files at the container are under that path, and by using the ${workspaceFolder} as value, VSCode knows that locally the project files are under the current opened directory.

Lastly, as a final step, click on the Start Debugging button and set the breaking points wherever you need.

Now, Xdebug is finally configured in your VSCode, and you can enjoy a more robust debugging tool with the potential to speed up your entire workflow.

---

I encourage you to leave this launch.json file with its content in the project, so other team members can just clone the project, run the containers, and enjoy a full-featured debug solution running in a container environment.

Happy coding!

Comments

[apmyp1990]

Hi, thanks for the guide. I am using VSCode from WSL2 with Docker installed in WSL2. But this setup will not work for me.
Do you have any suggestsions?

Thanks in advance

[Jack Miras]

Hi @apmyp1990, what problems are you facing?

Do you have any logs that you can share?

[apmyp1990]

I solved the problem - this line was missing:

xdebug.discover_client_host=true

[Lukáš Sladký]

Kudos for posting the answer to your problem after you'd solved it.

[apmyp1990]

A few days I ago I had to sovle the same problem again, because I hat to re-setup my local develpment. I was really happy to find my old setup here :-D

[Thanos Korakas]

On Windows with WSL2 and Docker I had to add the "hostname" property to the launch.json with the value "0.0.0.0".
"hostname": "0.0.0.0"
Also, I didn't have to specify my IP address on the xdebug.ini host field. I used the host.docker.internal, xdebug.client_host='host.docker.internal' and xdebug.discover_client_host=0

Thanks a lot for your great article

[Jack Miras]

@tkorakas how are you doing?

Thanks for adding the notes, I really appreciate it!

I just would like to leave it an observation about setting xdebug.client_host=host.docker.internal... Last time I've checked this didn't work for all OS (Linux, Mac, and Windows) while setting the IP works for the three of them.

For anyone else reading this comment, if your OS works by setting the client host this way, I recommend that you do it because it will save you from having to update your IP address from time to time.

Also, you probably had to set "hostname": "0.0.0.0" because of the change at the xdebug.client_host but it's not a big change.

Once again, thanks for adding the notes.

[Thanos Korakas]

Your comments makes absolute sense and it might save a lot of time from people reading this article.

Linux users where host.docker.internal is not working could try to add this lines on their docker compose file

extra_hosts:
- "host.docker.internal:host-gateway"

On the fpm container. Note: I didn't have the chance to test it

The main reason I used host.docker.internal is to be able to use this one different machines without having to change anything, or sharing with others.

Again, thanks a lot for your article. It was one the best written that I found on this topic

[apmyp1990]

I tried to tell my xdebug (in docker) the ip of my Windows Host hardcoded and via host copied from wsl to docker (that worked for another case), but the breakpoints were never hit.
Unfortunately I do not have any logs.

Here's my setup:

xdebug.ini

zend_extension=xdebug.so

xdebug.mode=debug,develop
xdebug.client_host=172.28.32.1
#same port as in launch.json
xdebug.client_port=9003
xdebug.idekey=VSCODE
xdebug.start_with_request=yes

launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug on Docker",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/amadeus360": "${workspaceFolder}"
            },
        },
    ]
}

[Fabio]

Hey really appreciated this guide, it helped me a lot to create my favorite dev env for laravel. I wrote about it here dev.to/snakepy/my-favorite-laravel...

I'd appreciate any improvement suggestions.

[Kaustab]

Firstly thanks for the post and also the helpful comment. I also faced similar issue where I created a drupal site with docker and using docker desktop in windows wsl.

This is what worked for me.

xdebug.ini
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.discover_client_host=true
xdebug.client_host=192.168.65.2
xdebug.output_dir=/tmp/xdebug
xdebug.log=/tmp/xdebug/xdebug-drupalapp.log
xdebug.idekey=docker

NOTE: where 192.168.65.2 is the host.docker.internal IP. For me the hostname didn't work, but by adding the IP directly worked. I've checked the IP from "/etc/hosts" file inside my docker container.

Updated my launch.json file inside vscode.

"configurations": ....
...
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"hostname": "0.0.0.0",
"log": true,
"pathMappings": {
"/opt/drupal": "${workspaceFolder}/drupal-app"
},
},

Start the debugging by clicking RUN&DEBUG or crlt+shift+D.

check the site with adding query parameter XDEBUG_SESSION_START=docker
where 'docker' is same as xdebug.idekey inside xdebug.ini
like:

http://drupalapp.localhost/blogs?XDEBUG_SESSION_START=docker

It worked !!

[Kachin Developer]

{
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 0,
            "runtimeArgs": [
                "-dxdebug.start_with_request=yes"
            ],
            "env": {
                "XDEBUG_MODE": "debug,develop",
                "XDEBUG_CONFIG": "client_port=${port}"
            }
        }

I want to run with docker container inside php how to setup

[Egor Demeshko]

thx. one thing to mentions, mayby useful
i use linux, and on another guide a added
extra_hosts:
- host.docker.internal:host-gateway
to my docker-compose file.
eveything started working as you described only after deleting this options.

and one more clarification
"pathMappings": {
"/app/": "${workspaceFolder}/symfony/"
},

left side(key) is route to app folder inside container, and righthand route to files on my machine, where IDE is opened.

[Raziel Rodrigues]

thanks!