Xdebug 3 + Docker + VS Code setup guide on Ubuntu

So here's my second annual (as in once-per-year) blog post. I hoped this would've happened more often, but oh well.

After many years of Sublime Text usage, I recently switched to VS Code, as the Sublime Text ecosystem for PHP development seems to be somewhat less active lately, based on my personal experience.

I was also recently starting work on a new Laravel project and decided to setup Xdebug so I could, well, debug. Most of the online guides I've found while hoping for a quick copy and paste configuration didn't end up working, and were in fact aimed at Xdebug 2 - whereas the new Xdebug 3 version changed some of the configuration setting keys. I spent a couple of hours getting everything to work nicely, and encountered a weird (but in hindsight, sensible) issue.

"Running in Docker" is not very specific, so I'll start by explaining my project setup. It's a Laravel app with a docker-compose.yml file in the project root, which looks a bit like this (documentation, unrelated services, and unrelated configuration settings removed for readability):

version: '3'

services:

  web:
    container_name: project--web
    build:
      context: ./docker/web
      args:
        HOST_UID: ${DOCKER_HOST_UID}
        HOST_GID: ${DOCKER_HOST_GID}
    restart: unless-stopped
    ports:
      - "${DOCKER_WEB_PORT}:80"
    volumes:
      - ./:/opt
    extra_hosts:
      - "host.docker.internal:host-gateway"

  php:
    container_name: project--php
    build:
      context: ./docker/php
      args:
        HOST_UID: ${DOCKER_HOST_UID}
        HOST_GID: ${DOCKER_HOST_GID}
    volumes:
      - ./:/opt
    extra_hosts:
      - "host.docker.internal:host-gateway"
    tty: true

The HOST_UID and HOST_GID are configured to be used by Apache in the web image and PHP in the php image so as not to mess up file permissions and ownership on the host machine.

For those curious, I also have the following services as a starting point for most Laravel projects:

a MySQL service as the app's database
a queue worker service (based on the same Docker image as the php service) for running artisan queue:work
a Node service for Node-related stuff (Yarn dependencies and the front-end build process)
Mailhog for local email testing
Beanstalk as a messaging queue
Beanstalk Aurora as a Beanstalk UI

Both the web and php services run a similar Docker image in terms of PHP - with the difference being that web also includes Apache through which the web application is served. I also have a local Nginx setup for proxying requests to various projects so that I can use https://project.localhost, https://mailhog.project.localhost etc. instead of having to remember the per-project ports for individual exposed services. For SSL in local development I use mkcert, though I guess none of this is too relevant for today's topic of Xdebug, and I should just make a separate blog post documenting that whole setup if anyone's interested.

Importantly though, the Docker images for running the web-app and CLI commands are based on ubuntu:bionic - I've been wanting to switch to the php images but just haven't gotten around to it yet. The Dockerfiles for the web and php images install PHP 7.4 from ppa:ondrej/php, along with a bunch of extensions including php7.4-xdebug - which, as of recently, ends up with Xdebug 3.0.1 installed in the image.

This whole guide should work just as well for PHP 8.0 as well as for older versions, though you probably shouldn't be using older versions anyway.

If you have a very specific setup that's similar to mine, you're gonna want to do the following:

Variables order

In my Docker images, PHP's default variables order was set to GPCS - which is not good because Xdebug looks for an environment variable in $_ENV when attempting to detect a trigger from a CLI command. Thus, my Dockerfile copies a file with the following contents to /etc/php/7.4/cli/conf.d/99-variables-order.ini:

; By default this is GPCS - we also want E so that $_ENV would be populated, and
; we could trigger Xdebug using an environment variable on the command line.
variables_order = "EGPCS"

This was giving me trouble and actually took me more time than everything else here to figure out why Xdebug wasn't working for me when attempting to trigger it from the command line.

Xdebug configuration

The Dockerfile also copies a file with the following contents to /etc/php/7.4/cli/conf.d/99-xdebug.ini (and /etc/php/7.4/apache2/conf.d/99-xdebug.ini in the web image):

xdebug.mode=debug
xdebug.client_host=host.docker.internal

The first line configures step debugging, and also affects how some other Xdebug configuration works by default (notably the default value of the xdebug.start_with_request setting).

The second line tells Xdebug which address to use to connect to the IDE - which is running on the host machine, and host.docker.internal is a special hostname which resolves to the host machine's IP address.

Note that my Dockerfile configuration which installs php7.4 and (among others) php7.4-xdebug from ppa:ondrej/php using apt will automatically enable the extension as well, so I don't need to explicitly do that. If you do, you'll want to also add zend_extension=/path/to/xdebug.so in this file.

host.docker.internal

As a sidenote, this wasn't supported on Linux at all for a long time until this PR was merged - and with it, Linux users still have to explicitly map host.docker.internal to the magic host-gateway value, which Docker then resolves to the host machine's IP address when starting the container and saves it in the container's /etc/hosts file. That's why the extra_hosts setting is needed in the docker-compose.yml file - and hopefully this shouldn't cause any issues in non-Linux (ie. Mac or Windows) Docker environments, though I haven't been personally able to test it yet.

VS Code

In VS Code you want to install the felixfbecker.php-debug extension (VS Code Marketplace, GitHub):

ext install felixfbecker.php-debug

You can follow the VS Code configuration section of that extension's installation instructions, but what worked for my setup was to add the following into my project's project.code-workspace file:

{
    // other stuff
    "launch": {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Listen for XDebug",
                "type": "php",
                "request": "launch",
                "port": 9003,
                "pathMappings": {
                    "/opt": "${workspaceFolder}"
                },
                "ignore": [
                    "**/vendor/**/*.php"
                ],
                "xdebugSettings": {
                    "max_children": 10000,
                    "max_data": 10000,
                    "show_hidden": 1
                }
            }
        ]
    }
}

The extension also suggests adding a "Launch currently open script" launch configuration, but I don't see how that would be useful in the context of a framework like Laravel, so I skipped it.

As for the other stuff, here's what the configuration settings mean:

name - just the name of the configuration which will be displayed in the debugger and the taskbar
type - should be php to tell VS Code that this configuration should run debugging with the PHP Debug extension we just installed
request - should be launch as that's appropriate for how we debug PHP with Xdebug
port - should be 9003 for Xdebug 3, which is the new default port that Xdebug will connect to - in older versions, the default port vas 9000, but we want to minimize our configuration work, so best to stick with the defaults when we can
pathMappings - this is important because Xdebug is running in the Docker container, where the app's files are under a different path; this is very configuration-specific so adjust it to your own setup, but my Dockerfiles use /opt as the WORKDIR and that's the volume I bind my project's directory to - hence my value for this configuration setting
ignore - optional paths that errors will be ignored from
xDebugSettings - consult the extension's documentation for more info, but I needed to set this higher than the default values because the defaults were too small for my use-case

To expand on the last point, one issue I had with the low default xDebugSettings was that my debugger would show, for example, that $_SERVER is an array() with ~60ish items, but when I expanded that variable, it would always only show the first 32 items and nothing else. Increasing these values fixed the problem.

So now we're done with configuring Xdebug and VS Code, so how do we actually debug?

There's two contexts in which it makes sense to debug PHP code - browser requests and CLI commands. Both are explained in Xdebug's documentation, but here's a short summary.

Browser

You want to install one (or more) of the following extensions, depending on which browser you're working with:

Once installed, you'll get an extension icon/button in your browser which enables you to select the Xdebug feature you want to trigger. I'm only interested in debugging, so when I want to do that, I'll click the icon and select the "debug" mode with the green bug icon.

Then I'll start a debugging session in VS Code by pressing F5 (which should be the default keybinding - if not, you can always open your "Run" panel in VS Code and click the little "play" icon next to the dropdown menu where "Listen for XDebug" should be selected).

I'll add a breakpoint where I need it (by simply clicking next to the line number), and refresh my browser page. What should happen is that Xdebug will connect to VS Code, which will in turn inform Xdebug about the breakpoint which was set, and then while the code is executing, if it reaches that line of code, it will pause execution and you can then step-debug in VS Code. Yay!

Note that depending on how the web server serving your PHP application is configured, you might get timeouts in your browser - but this article won't deal with that as it's already getting too long.

Don't forget to switch the browser extension's Xdebug mode back to "Disable" (gray bug icon) after you're done with it, to avoid invoking Xdebug on every request and slowing down performance.

Command Line

As with the browser-based flow, this again requires you to first start a debugging session in VS Code and set a breakpoint on a line of code.

To trigger Xdebug when running command-line applications (such as when unit testing or running an Artisan command), you need to configure a specific environment variable.

As I'm working with Docker Compose, I would usually run unit tests like this:

docker-compose run --rm php artisan test

The environment variable you need to set is XDEBUG_SESSION and with the Xdebug configuration described above, it can be set to any value, as long as it's set. Xdebug's documentation suggests XDEBUG_SESSION=1 so we'll go with that:

docker-compose run -e XDEBUG_SESSION=1 --rm php artisan test

That's it - when the code reaches a line where you've set a breakpoint, it should pause execution and focus that line within VS Code, where you can proceed to step through the code and track what's going on.

Conclusion

While this might seem like a long post compared to the actual amount of work that needs to be done to just configure Xdebug and VS Code and start debugging, I was attempting to describe my environment and setup in more detail so it can be more helpful to anyone running a similar setup - as well as trying to explain why all the required configuration is required in the first place, and what it does.

Hopefully this will work for you, but if it doesn't, feel free to let me know and I'll try to help out.

Stay healthy!