Skip to content

Xdebug + DDEV + Visual Studio Code

About

This article is about using Step Debugging.

"Xdebug's step debugger allows you to interactively walk through your code to debug control flow and examine data structures."

Setup: Windows WSL2

  • Ubuntu/WSL: do not install anything specific, everything is handled in the DDEV container;
  • vscode: Install extension: WSL (publisher Microsoft);
  • vscode: Install extension: PHP Debug (publisher Xdebug);
  • vscode: Install the PHP Debug extension also in WSL ("Install in WSL: Ubuntu");

Screenshot: xdebug extension

  • vscode: restart;

If using Docker Desktop

When running vscode from Ubuntu (code .) xdebug can't connect to the IDE.

Official istructions. Documentation.

Try (Ubuntu/WSL):

# Setup DDEV Xdebug location
ddev config global --xdebug-ide-location=wsl2
# Restart DDEV
ddev restart

Try (Ubuntu/WSL):

# Setup DDEV Xdebug location
ddev config global --xdebug-ide-location=container
# Restart DDEV
ddev restart

Try (Ubuntu/WSL):

# Get IP
hostname -I
# Setup DDEV Xdebug IP
ddev config global --xdebug-ide-location=__IP__
# Restart DDEV
ddev restart

Note: do not use custom ini file as some comments suggest, as the project may be run in different environments where the setup is different.

Configuration

.vscode/launch.json

{
    // Custom xdebug configuration for Visual Studio Code + DDEV
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}"
            }
        }
    ]
}

Usage

Enable in DDEV (make sure project is started): ddev xdebug on.

Start debugging in vscode:

  • Open "Run and Debug" (Ctrl+Shift+D)
  • Start debugging: "Listen for Xdebug" (F5)

Screenshot: xdebug start

Test: public/development/xdebug/xdebug-test.php

Add a breakpoint (click on the left of the line number) on the line with $var3, and another one on the line with the echo.

Screenshot: xdebug breakpoints

Navigate to the page xdebug-test.php:

Page loading is paused and the editor should now be in focus.

Go to vscode, some data should appear in the "Run and Debug" section.

Screenshot: xdebug inspect

Note: $var3 is not initialized because the break happens before the line is processed.

By clicking "Continue" we can go to the next breakpoint.

Screenshot: xdebug navigation

Now also $var3 has a value.

Notes

  • Breakpoints will be added before the next line with code (if adding on a blank line, it will be moved);
  • To debug also any errors that happen during execution (even if caught): Breakpoints > Everything. Screenshot: xdebug configuration
  • To stop debugging:
    • vscode: red square button (Shift+F5)
    • DDEV: ddev xdebug off

References