Xdebug 3 z DDEV dla Magento 2 – konfiguracja PHPStorm, VS Code i profiler

Xdebug 3 zmienił model konfiguracji w stosunku do wersji 2 – jedna dyrektywa xdebug.mode zastępuje kilkanaście ustawień. W połączeniu z DDEV konfiguracja debugowania dla Magento 2 jest teraz znacznie prostsza niż była 3 lata temu. Pokażę jak uruchomić step debugger w PHPStorm i VS Code, w tym debugowanie requestów HTTP, CLI i testów jednostkowych.

Xdebug 3 – model trybów

# Jeden parametr zamiast kilkunastu flag:
# xdebug.mode = off            # wyłączony
# xdebug.mode = debug          # step debugger
# xdebug.mode = profile        # profiler (cachegrind)
# xdebug.mode = trace          # function trace
# xdebug.mode = coverage       # code coverage
# xdebug.mode = debug,profile  # kilka trybów naraz

# W DDEV - przełącz tryb bez edycji pliku:
ddev xdebug on       # włącza debug mode
ddev xdebug off      # wyłącza
ddev xdebug status   # sprawdź aktualny stan

Konfiguracja w DDEV

# DDEV obsługuje Xdebug automatycznie - nie trzeba nic pisać w php.ini
# Ale możesz nadpisać ustawienia w .ddev/php/xdebug.ini:

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = trigger   ; nie startuj na każdym req - tylko z triggerem
xdebug.discover_client_host = true    ; auto-wykryj host IDE
xdebug.client_port = 9003
xdebug.idekey = PHPSTORM
xdebug.log_level = 0                  ; 0 = bez logów, 7 = verbose

# Po zmianie konfiguracji:
ddev restart
ddev xdebug on

# Weryfikacja
ddev exec php -v
# Powinna pojawić się linia: with Xdebug v3.x.x

PHPStorm – konfiguracja

# 1. Settings > PHP > Debug
#    Debug port: 9003 (Xdebug 3 domyślnie)
#    Nie: 9000 (to był Xdebug 2)

# 2. Settings > PHP > Servers
#    Name: ddev-magento (lub nazwa twojego projektu)
#    Host: magento.ddev.site (lub twoja domena DDEV)
#    Port: 443
#    Debugger: Xdebug
#    Path mappings:
#      /home/user/projects/magento -> /var/www/html

# 3. Run > Start Listening for PHP Debug Connections (ikona słuchawki)

# 4. Trigger przez URL (start_with_request = trigger):
# Zainstaluj rozszerzenie Xdebug Helper dla Chrome/Firefox
# Lub dodaj ?XDEBUG_SESSION=PHPSTORM do URL
# Lub użyj cookie: XDEBUG_SESSION=PHPSTORM

Debugowanie CLI (bin/magento)

# Xdebug w CLI wymaga ustawienia zmiennej środowiskowej
# W DDEV:
ddev exec -e XDEBUG_SESSION=1 php bin/magento cache:flush

# Lub przez .ddev/commands/web/debug-cli (custom command):
# #!/bin/bash
# XDEBUG_SESSION=1 php "$@"
# Użycie: ddev debug-cli bin/magento indexer:reindex

# Bez DDEV - przez php.ini CLI:
# /etc/php/8.3/cli/conf.d/20-xdebug.ini
# xdebug.mode = debug
# xdebug.start_with_request = yes  ; startuj zawsze dla CLI
# xdebug.client_host = 127.0.0.1
# xdebug.client_port = 9003

Debugowanie testów PHPUnit

# W DDEV - uruchom testy z Xdebug:
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/

# W PHPStorm: Run > Debug > PHPUnit (skonfiguruj interpreter jako remote Docker)
# Settings > PHP > Test Frameworks > PHPUnit by Remote Interpreter

VS Code – konfiguracja

// .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"
            ]
        }
    ]
}

Profilowanie zamiast debugowania

# Profiler generuje cachegrind - analizuj w Qcachegrind (Linux) lub Webgrind
ddev exec sh -c 'XDEBUG_MODE=profile XDEBUG_SESSION=1 php bin/magento cache:flush'

# Lub przez URL z triggerem:
# https://magento.ddev.site/catalog/category/view/id/1?XDEBUG_PROFILE=1

# Pliki cachegrind lądują w /tmp/
ddev exec ls /tmp/cachegrind*

# Kopiuj do hosta i otwórz w Qcachegrind:
ddev exec cat /tmp/cachegrind.out.1 > /tmp/local_cachegrind.out

Podsumowanie

Xdebug 3 z DDEV to konfiguracja „działa od razu” dla większości przypadków. Tryb trigger (nie startuj na każdym requescie) jest właściwym wyborem dla sklepów – debuger aktywuje się tylko gdy tego chcesz. Najczęstszy błąd po migracji z Xdebug 2 to użycie portu 9000 zamiast 9003. Profiler (tryb profile) przyspiesza diagnozę wolnych stron bardziej niż ręczne dodawanie var_dump.