PHP Debugging mit Xdebug auf dem Ops One Managed Server

Diese Anleitung bezieht sich auf einen Managed Server der Version 10. Für die meisten Managed-Server-Versionen ist die Funktionsweise gleich oder ähnlich. Bei Unsicherheiten schaust du am besten kurz in die Dokumentation deines Managed Servers.

Voraussetzungen lokal

Xdebug funktioniert mit jeder integrierten Entwicklungsumgebung (IDE), welche das DBGp-Protokoll unterstützt. In dieser Anleitung benutzen wir das kostenlose Visual Studio Code.

Folgende Voraussetzungen müssen lokal erfüllt sein:

• Zugang zur jeweiligen Website per SSH
• Visual Studio Code mit den Erweiterungen Remote SSH und PHP Debug

“Remote SSH” benötigen wir, damit wir in der IDE denselben Code sehen wie auf dem Server. Und “PHP Debug” liefert uns die notwendige Unterstützung, damit das Zusammenspiel mit Xdebug funktioniert. Stelle sicher, dass beides installiert ist.

Voraussetzungen Server

Folgende Voraussetzungen müssen auf dem Server erfüllt sein:

• Website mit Website-Type PHP (oder TYPO3, WordPress, etc.)
• Xdebug wird als PHP-Erweiterung geladen
• 2 GB RAM für Visual Studio Code Remote SSH

Laden kannst du Xdebug, indem du das PHP-Konfigurationsfile der jeweiligen Website editierst. Führe dazu mittels SSH auf dem Server folgende Befehle aus:

# Xdebug PHP-Erweiterung laden
$ echo 'zend_extension = xdebug.so' >> ~/cnf/php.ini

# Konfigurationsänderung anwenden
$ php-reload

# Geladene PHP-Module anzeigen
$ php -m

Ein PHP-Reload sorgt dafür, dass die Änderung angewendet wird. Anschliessend kannst du mit php -m prüfen, ob Xdebug geladen wird. Ist das nicht der Fall, so könnte es sein, dass Xdebug für die verwendete PHP-Version nicht zur Verfügung steht. Falls es sich um eine aktuelle Version handelt, kannst du mit uns Kontakt aufnehmen, damit wir uns das anschauen. Bei End-of-Life Versionen besteht die Möglichkeit, dass Xdebug aus Kompatibilitätsgründen nicht mehr zur Verfügung steht.

Stelle zudem sicher, dass dein Server über 2 GB freien RAM und über mindestens 2 CPU verfügt. Hierbei handelt es sich um die empfohlenen System Requirements für Visual Studio Code Remote SSH. Da Server-Ressourcen auf die Minute genau abgerechnet werden, kannst du die Ressourcen auch kurzfristig erhöhen und nach dem Debuggen wieder reduzieren, sodass nur minimale Kosten anfallen.

Visual Studio Code und Remote SSH

Damit du in Visual Studio Code und auf dem Server dieselben Dateien siehst, arbeiten wir mit Remote SSH direkt auf dem Server. Öffne dazu die Command-Palette (⇧+Ctrl+P für Linux und Windows oder ⇧+⌘+P für Mac) und suche nach “Remote-SSH: Connect to Host”. Im nächsten Schritt kannst du die Serveradresse im Format website@server einfügen und dich direkt mit dem Server verbinden. Falls du gefragt wirst, welchen Ordner du öffnen möchtest, kannst du das Home-Verzeichnis deiner Website /home/<website> angeben.

Nun befindest du dich auf dem Server und kannst in Visual Studio Code Dateien editieren. Zudem kannst du das in Visual Studio Code integrierte Terminal benutzen, um dich auf dem Server fortzubewegen oder Befehle auszuführen.

Die Verwendung von Remote SSH hat folgende Vorteile:

• Du siehst direkt in Visual Studio Code dieselben PHP-Files wie auf dem Server.
• Xdebug des Servers muss mit Visual Studio Code kommunizieren. Hierfür exponiert die IDE einen Port, an welchen Xdebug die Daten sendet. Wird Visual Studio Code mit Remote SSH direkt auf dem Server ausgeführt, musst du dich nicht um SSH-Port-Forwarding kümmern (falls du Remote SSH nicht verwenden möchtest: In der Dokumentation beschreiben wir das Vorgehen mit SSH-Port-Forwarding).

Visual Studio Code Debugging-Konfiguration

Als Nächstes musst du dem in Visual Studio Code integrierten Debugger mitteilen, auf welchem Port der Debugger lauschen soll. Hierfür legen wir eine neue Datei .vscode/launch.json an. Du kannst die Datei von Hand oder mittels Command-Palette anlegen ("Debug: Add Configuration"). Inhalt von .vscode/launch.json:

{
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003
    }
  ]
}

Der verwendete Port muss auf dem Server frei sein. Das kannst du mit netstat -tulpn überprüfen. Falls der Port belegt ist, kannst du einen anderen non-privileged Port benutzen (grösser oder gleich 1024).

Falls das Anlegen der Konfiguration funktioniert hat, findest du im Debugging-Bereich von Visual Studio Code einen neuen Button mit der Beschriftung “Listen for Xdebug”:

Falls du den Button nicht siehst, kontrolliere nochmals, ob alle Visual Studio-Code-Erweiterungen installiert und aktiviert sind, .vscode/launch.json vorhanden ist und starte ggf. Visual Studio Code neu.

Konfiguration von Xdebug

Jedes Mal, wenn du den “Listen von Xdebug”-Button betätigst, lauscht der Visual Studio Code Debugger auf dem Server unter 127.0.0.1:9003 und wartet, bis er Daten von Xdebug erhält. Damit Xdebug die Daten an den richtigen Ort sendet, ergänzen wir das ~/cnf/php.ini wie folgt:

# Lädt Xdebug
zend_extension = xdebug.so

# Aktiviert Debug Mode
xdebug.mode = debug
xdebug.start_with_request = trigger

# Verbindung zu Visual Studio Code
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003 # denselben Port wie in .vscode/launch.json

Du kannst das Konfigurationsfile auf der Konsole per SSH oder direkt in Visual Studio Code bearbeiten. Nach dem Bearbeiten muss die Konfiguration mit einem php-reload⁣ angewendet werden.

Debugging mit Breakpoints

Nun bist du bereit, dein PHP-Script zu debuggen. Damit das Debugging funktioniert, musst du den “Listen for Xdebug”-Button betätigt haben. Das Debugging startet, sobald Xdebug den String XDEBUG_TRIGGER als GET-Parameter, POST-Request oder Cookie sieht.

Nachfolgend Beispiele mit Curl:

# GET-Request
curl https://example.com/?XDEBUG_TRIGGER

# POST-Request
curl -X POST --data 'XDEBUG_TRIGGER' https://example.com

# Cookie
curl --cookie "XDEBUG_TRIGGER;path=/;" https://example.com

Mit gesetzten Breakpoints sieht das dann wie folgt aus:

Optional kannst du Browser-Erweiterungen nutzen, welche dich beim Senden von XDEBUG_TRIGGER unterstützen. In der Dokumentation von Xdebug findest du eine Auswahl.

Zusammenfassung

In dieser Anleitung hast du folgende Schritte ausgeführt:

1. Visual Studio Code mit den Erweiterungen Remote SSH und PHP Debug installiert.
2. Deine Website per Remote SSH in Visual Studio Code geöffnet.
3. Die PHP-Konfiguration ~/cnf/php.ini editiert und Xdebug aktiviert.
4. Den Visual Studio Code Debugger mit .vscode/launch.json konfiguriert.
5. “Listen for Xdebug” betätigt und das Debugging mit XDEBUG_TRIGGER gestartet.

In Visual Studio Code kannst du nun beliebig Breakpoints setzen und nachvollziehen, was bei einem Request passiert.