Xdebug zum Debuggen von entferntem PHP-Code

Mit Xdebug können Sie PHP-Code mit Haltepunkten schrittweise durchlaufen und die Variablen einer Anfrage in einer kompatiblen IDE untersuchen.

Verwenden Sie es vorzugsweise lokal oder im Staging. Eine schrittweise Sitzung kann der IDE Variablenwerte, Zugangsdaten, Tokens und personenbezogene Daten offenlegen, die die Anfrage verarbeitet. Müssen Sie es ausnahmsweise in der Produktion einsetzen, beschränken Sie den Test auf eine autorisierte Anfrage, verwenden Sie einen privaten Trigger und deaktivieren Sie die Erweiterung sofort danach.

Xdebug kann je nach aktivem Modus einen spürbaren Overhead verursachen und deaktiviert das JIT von PHP, solange es geladen ist. Prüfen Sie seine tatsächliche Version; leiten Sie sie nicht allein aus der PHP-Version ab.

Verfügbarkeit prüfen und Xdebug 3 aktivieren

Öffnen Sie cPanel > PHP-Version auswählen für die Version, die den Pfad ausführt. Diese Anleitung gilt nur, wenn die Auswahl die Erweiterung xdebug und unter Options die Option xdebug.mode anbietet. Aktivieren Sie die Erweiterung und setzen Sie xdebug.mode auf debug. Diese Option wird beim Start von PHP angewendet und lässt sich weder über .htaccess noch über .user.ini festlegen.

Fehlt eine dieser Optionen, gehen Sie nicht davon aus, dass Xdebug für diese Version verfügbar ist. Versuchen Sie nicht, im Konto eine andere Erweiterung zu installieren oder zu laden.

Wenn der PHP-Handler der Domain Xdebug-Direktiven in .htaccess zulässt, fügen Sie vorübergehend hinzu:

php_value xdebug.start_with_request trigger
php_flag xdebug.start_upon_error Off
php_flag xdebug.discover_client_host Off
php_value xdebug.client_host 127.0.0.1
php_value xdebug.client_port 9003
php_value xdebug.trigger_value VALOR_ALEATORIO_LARGO

Ersetzen Sie VALOR_ALEATORIO_LARGO durch einen privaten Wert. Diese Optionen legen den Start per Trigger fest, deaktivieren den automatischen Start bei Fehlern und verhindern, dass das Ziel aus Headern ermittelt wird. Prüfen Sie die tatsächlich wirksamen Werte: Code, der xdebug_break() aufruft, kann ebenfalls eine Verbindung starten. Der private Trigger steuert den üblichen Test, ist aber kein Authentifizierungsmechanismus des Protokolls. Verursachen die Direktiven einen 500-Fehler, entfernen Sie sie und prüfen Sie das Protokoll: Der Code allein beweist nicht, dass der Handler sie ablehnt.

Einen umgekehrten SSH-Tunnel einrichten

Xdebug baut die Verbindung zur IDE auf; die IDE verbindet sich nicht mit Xdebug. In dieser Konfiguration verbindet sich Xdebug auf dem Server mit 127.0.0.1:9003, und der SSH-Tunnel leitet diese Verbindung an 127.0.0.1:9003 auf Ihrem Rechner weiter, wo die IDE lauscht.

Aktivieren Sie vorher den SSH-Zugang und richten Sie einen Schlüssel nach der Anleitung zum SSH-Zugang ein.

Führen Sie unter Linux oder macOS aus:

ssh -N -p 93 \
  -o ExitOnForwardFailure=yes \
  -R 127.0.0.1:9003:127.0.0.1:9003 \
  USUARIO_CPANEL@TU_DOMINIO.COM

-R öffnet den Port 9003 nur auf der Loopback-Schnittstelle des Servers und leitet ihn an den Port 9003 Ihres Rechners weiter. Halten Sie die Sitzung nur während des Tests offen. Kann SSH die Weiterleitung nicht einrichten, bricht es mit einem Fehler ab; legen Sie stattdessen nicht den Port des Debuggers im Internet offen.

Konfigurieren Sie unter Windows PuTTY mit der Domain und dem Port 93 und verwenden Sie den in cPanel autorisierten SSH-Schlüssel. Legen Sie unter Connection | SSH | Tunnels eine Remote-Weiterleitung von 127.0.0.1:9003 zum Ziel 127.0.0.1:9003 an. Aktivieren Sie keine Optionen, die das Lauschen auf anderen Schnittstellen des Servers erlauben. Lehnt die Sitzung die entfernte Weiterleitung ab, steht dieser Weg für das Konto nicht zur Verfügung.

Die IDE konfigurieren und die Anfrage reproduzieren

Öffnen Sie in der IDE dieselbe Version des Codes, die bereitgestellt ist, und konfigurieren Sie die Zuordnung zwischen dem entfernten Pfad und dem lokalen Projekt. Stellen Sie den Xdebug-Port 9003 ein, aktivieren Sie das Lauschen auf Verbindungen und setzen Sie die Haltepunkte.

Verwenden Sie in PhpStorm Run > Start Listening for PHP Debug Connections. Konfigurieren Sie in NetBeans den Port 9003 und die Zuordnung der entfernten Pfade. Es ist nicht nötig, das Projekt per FTP zu synchronisieren, um eine Debug-Sitzung zu empfangen.

Aktivieren Sie den Trigger mit einer kompatiblen Browsererweiterung, die mit demselben privaten Wert konfiguriert ist, oder hängen Sie XDEBUG_TRIGGER=VALOR_ALEATORIO_LARGO nur an die Testanfrage an. Reproduzieren Sie die nötige Operation ein einziges Mal. Ein Aufruf der URL ohne Trigger darf keine Sitzung starten.

Deaktivieren Sie danach den Trigger, schließen Sie den SSH-Tunnel, entfernen Sie die vorübergehenden Direktiven, setzen Sie xdebug.mode auf off oder deaktivieren Sie die Erweiterung und prüfen Sie, dass kein Xdebug-Protokoll mit Daten der Sitzung zurückbleibt.

Wenn Sie die Leistung analysieren möchten, statt den Code schrittweise zu durchlaufen, verwenden Sie PHP X-Ray.

Grenzen des Tunnels und Prüfung

Loopback verhindert das Lauschen auf einer öffentlichen Schnittstelle, garantiert aber keine Isolation zwischen allen Benutzern eines Shared-Servers. Lassen Sie sich vom Anbieter bestätigen, dass die Weiterleitung für Ihre Umgebung erlaubt und isoliert ist. Ist der Port belegt, vereinbaren Sie einen anderen entfernten Port und passen Sie xdebug.client_port an; ändern Sie nicht die Daten eines anderen Benutzers.

Prüfen Sie zuerst, dass eine Anfrage ohne Trigger keine Sitzung startet, und dann, dass die Testanfrage den richtigen Haltepunkt erreicht. Veröffentlichen Sie keine URL mit dem Trigger: Sie kann in Verläufen oder Protokollen landen. Löschen Sie danach auch das Debug-Cookie. Lesen Sie die Debug-Optionen von Xdebug, wenn die Sitzung unerwartet startet.