Xdebug 3 with DDEV for Magento 2 – PHPStorm, VS Code and profiler setup

Xdebug 3 changed the configuration model compared to version 2 – a single xdebug.mode directive replaces a dozen settings. Combined with DDEV, setting up debugging for Magento 2 is now significantly simpler than it was three years ago. I show how to run the step debugger in PHPStorm and VS Code, including debugging HTTP requests, CLI commands and unit tests.

Xdebug 3 – mode model

# One parameter instead of a dozen flags:
# xdebug.mode = off            # disabled
# xdebug.mode = debug          # step debugger
# xdebug.mode = profile        # profiler (cachegrind)
# xdebug.mode = trace          # function trace
# xdebug.mode = coverage       # code coverage
# xdebug.mode = debug,profile  # multiple modes at once

# In DDEV - switch mode without editing a file:
ddev xdebug on
ddev xdebug off
ddev xdebug status

Configuration in DDEV

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = trigger   ; start only on trigger, not every request
xdebug.discover_client_host = true
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.log_level = 0

ddev restart
ddev xdebug on
ddev exec php -v
# Should show: with Xdebug v3.x.x

PHPStorm – configuration

# 1. Settings > PHP > Debug
#    Debug port: 9003 (Xdebug 3 default)
#    Not: 9000 (that was Xdebug 2)

# 2. Settings > PHP > Servers
#    Host: magento.ddev.site
#    Port: 443
#    Debugger: Xdebug
#    Path mappings:
#      /var/www/html -> /home/user/projects/magento

# 3. Run > Start Listening for PHP Debug Connections

# 4. Trigger via URL (start_with_request = trigger):
# Install Xdebug Helper extension for Chrome/Firefox
# Or add ?XDEBUG_SESSION=PHPSTORM to URL

Debugging CLI (bin/magento)

# Xdebug in CLI requires setting an environment variable
ddev exec -e XDEBUG_SESSION=1 php bin/magento cache:flush

# Without DDEV - via CLI php.ini:
# xdebug.mode = debug
# xdebug.start_with_request = yes   ; always start for CLI
# xdebug.client_host = 127.0.0.1
# xdebug.client_port = 9003

Debugging PHPUnit tests

ddev xdebug on
ddev exec -e XDEBUG_SESSION=1 \
    vendor/bin/phpunit \
    -c dev/tests/unit/phpunit.xml.dist \
    app/code/Vendor/Module/Test/Unit/

VS Code – configuration

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug (DDEV)",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "ignore": ["**/vendor/**/*.php"]
        }
    ]
}

Profiling instead of debugging

# Profiler generates cachegrind - analyse in Qcachegrind or Webgrind
ddev exec sh -c 'XDEBUG_MODE=profile XDEBUG_SESSION=1 php bin/magento cache:flush'

# Or via URL trigger:
# https://magento.ddev.site/catalog/category/view/id/1?XDEBUG_PROFILE=1

ddev exec ls /tmp/cachegrind*

Summary

Xdebug 3 with DDEV is a “works out of the box” configuration for most cases. The trigger mode (do not start on every request) is the right choice for shops – the debugger activates only when you want it. The most common mistake after migrating from Xdebug 2 is using port 9000 instead of 9003. The profiler (profile mode) speeds up diagnosing slow pages faster than manually adding var_dump.