WordPress & Docker: Schnelles Xdebug 3 Setup mit VS Code

Ein aktiver PHP-Debugger kann die WordPress-Performance im Docker-Container massiv einbremsen. Die Lösung ist der Trigger-Modus: Xdebug läuft erst dann, wenn du es über eine Browser-Erweiterung aktivierst. Im normalen Entwickler-Alltag läuft deine Website mit gewohnter 100%iger Geschwindigkeit.

1. Docker Compose anpassen

Damit der Docker-Container mit dem VS Code Host-System kommunizieren kann, füge extra_hosts zu deiner docker-compose.yml hinzu:

services:
  wordpress:
    image: wordpress:latest
    container_name: wordpress_app
    volumes:
      - ./html:/var/www/html
    extra_hosts:
      host.docker.internal: host-gateway

Wende die Änderungen im Terminal an:

docker compose up -d

2. Xdebug im Container installieren & konfigurieren

Installiere das Xdebug-Modul im laufenden WordPress-Container:

docker exec -it wordpress_app bash -c "pecl install xdebug && docker-php-ext-enable xdebug"

Erstelle anschließend die Konfigurationsdatei. Der Schlüssel zur Performance ist xdebug.start_with_request=trigger:

docker exec -it wordpress_app bash -c 'cat <<EOF > /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
EOF'

Starte den Container neu, um die Einstellungen zu übernehmen:

docker restart wordpress_app

3. VS Code vorbereiten

Stelle sicher, dass die Erweiterung PHP Debug (xdebug.php-debug) in VS Code installiert ist. Erstelle dann die Datei .vscode/launch.json in deinem Projektverzeichnis:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

4. Browser-Extension installieren

1. Installiere die Erweiterung Xdebug Helper (von JetBrains) in deinem Browser (Chrome/Firefox/Safari).
2. Öffne die Optionen / Settings der Erweiterung.
3. Trage im Feld Debug-Trigger oder Xdebug Cloud-Schlüssel den Wert VSCODE ein und speichere ab.

5. So nutzt du das Setup

• Normales Arbeiten: Das Käfer-Icon im Browser ist grau (Disable). WordPress lädt gewohnt schnell.
• Debugging starten:
  1. Drücke F5 in VS Code (Statusleiste wird orange).
  2. Schreibe testweise xdebug_break(); in eine PHP-Datei (oder setze einen Breakpoint per F9).
  3. Klicke im Browser auf das Käfer-Icon und wähle Debug (Icon wird grün).
  4. Lade die Seite neu – VS Code hält exakt an deinem Code-Abschnitt an!