Debugging Wordpress with XDebug, DDEV and VSCode

This article is aimed to people developing Wordpress sites and using DDEV and VSCode. DDEV makes PHP development extremely simple, but for some reason, in my experience, setting up XDebug has always been a bit challenging.

1. Enable XDebug in DDEV

In the file located at .ddev/config.yaml look for the property named xdebug_enabled and set it to true. It should look like this

xdebug_enable: true

2. Install and configure PHP Debug

In VSCode, install the PHP Debug extension

Once installed, click on the Run and Debug icon on the left menu:

Click on create a launch.json file and then in the Select environment dropdown, click on PHP

This will create a launch.json file in your current project that will look similar to this:

Each one of the objects in the configuration represent a configuration profile. The one we’ll use is the one that says Listen for XDebug.

XDebug 2 uses port 9000 and XDebug 3 uses port 9003.

From what we got, we only need to add the pathMappings so the debugger knows where the application’s root is at. In my case, I have many folders (one folder per each wordpress site) in my workspace root in VSCode, similar to this:

• site-a
• site-b
• site-c

So, if I’m setting up the debugger on site-a, the configuration needs to be set like this:

{
  "name": "Listen for XDebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceRoot}/site-a"
  }
}

/var/www/html is the path inside of ddev’s docker image and ${workspaceRoot}/site-a is the root of my site in VSCode

If your workspace is already at the root level of your site, for example it is opened at site-a, you shouldn’t need to add any additional path after ${workspaceRoot}

3. Set the correct XDebug port on DDEV

For some reason, my DDEV came with XDebug 3, but PHP is configured to used port 9000 for XDdebug, so the best bet is to tell DDEV to use the port you need. In my case I have XDebug 3, so I need port 9003 (this matches what we have in launch.json). To do so, create a file located at .ddev/php/ named xdebug_client_port.ini and in it add this:

[PHP]
xdebug.client_port=9003

4. Restart ddev

Now that all configurations are ready, restart ddev if it was already running by executing:

ddev restart

5. Start debugging

First, set a breakpoint in the line of code you want to pause the debugger at:

Then, In the RUN AND DEBUG option in VSCode, select “Listen for XDebug” in the dropdown and click on the green play icon to its left

The debugger will start and the bottom bar of VSCode should turn orange

Open the site in the browser and the debugger should pause in the breakpoint you set

And that’s it. Happy debugging!