Skip to content

Latest commit

 

History

History
98 lines (75 loc) · 6.18 KB

xdebug.md

File metadata and controls

98 lines (75 loc) · 6.18 KB
Raw

Debugging PHP with Xdebug v3 inside Docker using VSCode

Assumptions / Prerequisites

  • Xdebug v3+ inside Docker (e.g. php:7.3-apache Docker image)
  • Running Docker v20.10+
  • VSCode with PHP Debug Extension

Objective

I want to debug my running dockerized PHP web application code from within VSCode using Xdebug.

What I discovered trying to make this work

  • Xdebug v3 has breaking changes from v2. The config file and behavior of v3 is very different from v2. Most of the internet resources I found on the internet pertain to Xdebug v2. Once I realized I was running Xdebug v3, it became easier to get this working. Basically, forget what you know about Xdebug 2 configuration files and go read the docs.
  • Normally, processes inside a Docker container shouldn't need to connect to services on the host. The way Xdebug is designed (as I understand it), Xdebug inside of the Docker container is more like a "client" that connects to a debug "xdb server" running in VSCode. This connection is established from inside the Docker container out to the host. Thus, it's not necessary to expose any ports to the container, rather, the container needs to know how to connect to the host.
  • Docker v20.10+ includes a special host.docker.internal hostname that containers can access when enabled. Some earlier versions of Docker have OS-specific ways of enabling this. Best to stick with Docker 20.10+

Steps

  1. Install VSCode and the PHP Debug extension by Felix Becker (or xdebug.php-pack when you are using GitHub Codespaces).
  2. Build a Docker image from the official PHP image. e.g. php:7.3-apache
  3. In your image, install Xdebug v3 using the apt install php-xdebug, note that you might need to change the command to better suit your needs (diffrent package managers, etc)
  4. In your image, copy in your application code
  5. Create a info.php that includes the line Xdebug_info(); which you can access in the host's web browser to verify what Xdebug settings are enabled
  6. Create a VSCode debug configuration for Xdebug like this (in your host at the root of your project {project_root}/.vscode/launch.json):
    {
      "name": "Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html/": "${workspaceRoot}/src/"
      }

Note that the port must match what Xdebug is configured to connect to, and the pathMappings may be different for your application. first part in the mapping is your application root in the container, second part is it's mapping to your workspace.

  1. in your docker-compose.yaml add:
    extra_hosts:
      - "host.docker.internal:host-gateway"

or if you are using docker to runa container use:

docker run --add-host "host.docker.internal:host-gateway" {rest of command}
  1. You can control Xdebug configuration via environment variables. This could be helpful for dev/prod setups. In my setup, I chose to enable Xdebug via an environment variable in my docker-compose.yaml file:
    environment:
      - Xdebug_MODE=develop,debug
  1. Xdebug configuration lives on /etc/php/8.1/cli/conf.d/20-xdebug.ini, this might be diffrent for you based on the platform you use or the php version, search for 20-xdebug.ini file until you find it. I customized mine like the following, including the default mode set to off (which my environment variable above overrides to develop,debug)
[Xdebug]
zend_extension=Xdebug
Xdebug.mode=off
Xdebug.start_with_request = yes
Xdebug.client_host = "host.docker.internal"
Xdebug.idekey="VSCODE"
Xdebug.log=/tmp/Xdebug_remote.log

in case you don't want to use COPY in Dockerfile to include this configuration into your image while you build it, you can still manually map this confguration to your container. (this is my preferred way)

  1. Now, when you start your container, you should be able to start up the VSCode debugger and get it to stop on breakpoints in your web application code.

Tips

  • Xdebug 3 defaults to port 9003, while the old Xdebug 2 defaults to port 9000. Watch out for this in examples on the internet.
  • Once I got the pathMappings variable correctly setup in VSCode, I was able to step through my PHP application running in Docker! Unfortunately, my Composer dependencies only exist inside the container, not on the host. Thus, VSCode encountered errors e.g. "could not find file /var/www/html/vendor/blah" referring to a PHP dependency managed by Composer when stepping into vendor libraries. In my situation, I don't want Composer dependencies to exist outside of Docker, so I'm not able to debug/step through the dependent libraries. If you want this ability, make sure that you have a copy of the dependencies on your host (or do the composer install step on your host) before debugging.
  • Turn off Breakpoints: Everything in the VSCode debugger. This was causing VSCode to want to step inside vendor libraries.

How to Debug your Xdebug setup :)

  • I used netcat and ping inside my Docker container to verify that I could talk to the host from inside the Docker container. (apt install -y inetutils-ping netcat) Here's a netcat example to verify that port 9003 is open on the host and I can talk to it from inside the Docker container:
root@44eabbdd0967:/var/www/html# nc -vz host.docker.internal 9003
host.docker.internal [172.18.0.1] 9003 (?) open

If instead of open you get a message like Connection refused then you know something isn't setup correct yet, OR you haven't clicked the green triangle in VSCode to run the debugger (so it can listen for connections on port 9003). On my setup the VSCode status bar changes colors to orange when the debugger is running

Internet References

These references were helpful to me in putting this together for my project: