Remote Debugging mit PHPStorm und XDebug

Grundlagen

Wie funktioniert Remote Debugging grundsätzlich? Durch einen Aufrufparameter erfährt der PHP Debugger (in diesem Fall XDebug), dass Remote Debugging aktiviert werden soll. Dann wird eine Client - Server Verbindung zwischen dem Debugger und der IDE (in diesem Fall PHPStorm) aufgebaut. Diese Verbindung läuft außerhalb des "normalen" HTTP-Requests, bei XDebug per default auf Port 9000.

Besteht diese Verbindung, kann die IDE Befehle an den Debugger schicken. Beispielsweise, dass er an einer bestimmten Stelle anhalten soll und auf weitere Befehle der IDE warten möge (Breakpoint).

PHPStorm bietet gleich 3 verschiedene Möglichkeiten, mit dem Debugger in Kontakt zu treten:

  1. Listen PHP Debug Connections
  2. PHP Web Application
  3. PHP Remote Debug

Für eine detaillierte Erklärung zu den einzelnen Verfahren sei auf [1] verwiesen.

Installation von XDebug

Der erste Schritt in Richtung Remote Debugging ist die Installation von XDebug. Wer nachschauen möchte, ob XDebug auf seinem Server bereits installiert ist, kann auf der Kommandozeile mit 

php -i

ein php-info ausgeben lassen. Hier erscheint ggf. auch XDebug. In diesem Fall kann dieser Schritt übersprungen werden. Ansonsten kann mit 

pear install pecl/xdebug

XDebug installiert werden.

Konfiguration von XDebug

Ich beschreibe hier nur die für das Remote Debugging relevante Konfiguration von XDebug. XDebug hat noch weitere Funktionen über das Remote-Debugging hinaus, dazu möchte ich auf die XDebug Webseite [2] verweisen.

Ich musste meiner php.ini folgende Zeilen hinzufügen, um XDebug für Remote Debugging zu aktivieren:

 

 

# ACHTUNG hier unbedingt zend_extension und nicht extension=xdebug.so verwenden
# Letzteres hat bei mir dazu geführt, dass alles zu gehen schien und doch nichts funktioniert hat
zend_extension = /usr/lib/php/modules/xdebug.so

# Schaltet remote debugging grundsätzlich ein
xdebug.remote_enable=On

# Wenn nicht für jeden Client ein Debugging aktiviert sein soll
# kann hier ein host angegeben werden, auf den das Debugging
# beschränkt werden soll (IP Adresse des Rechners mit der IDE)
#xdebug.remote_host=192.168.1.100

# Schaltet Remote Debugging für alle Hosts an
xdebug.remote_connect_back=On

# Schaltet Remote Debugging per default an (keine Aktivierung durch Session / URL nötig)
xdebug.remote_autostart=On

# Schreibt den Datenverkehr zwischen XDebug und IDE in ein log file (bei Fehlersuche sehr zu empfehlen!)
xdebug.remote_log=/tmp/xdebug.log
XDebug-Konfiguration in php.ini

Nach dem Ändern der php.ini Datei nicht vergessen, den Webserver neu zu starten!

Konfiguration von PHPStorm

Nach der Konfiguration des Webservers muss nun noch PHPStorm für die Verwendung von Remote Debugging konfiguriert werden. Dazu sind folgende Schritte notwending:

1. Einrichtung eines Webservers

PHPStorm muss wissen, mit welchem Server das Remote Debugging ausgeführt werden soll. Dazu in den Einstellungen unter PHP > Servers den Webserver eintragen.

Sehr wichtig: Wenn die Projekt-Dateien nicht lokal auf dem Rechner vorhanden sind, sondern gemountet werden, muss PHPStorm mitgeteilt werden, wo die entsprechenden Dateien auf dem Server liegen. Dies wird über sogenannte "path mappings" vorgenommen. Es reicht meist aus, wenn das Root-Verzeichnis des Web-Projektes ein entsprechendes Mapping bekommt. 

Konkretes Beispiel: Das Projektverzeichnis ist unter /Volumes/project gemountet. Auf dem Webserver liegt das Projektverzeichnis unter /var/www/projects/project. Dann muss im path mapping für das Projektverzeichnis project das path mapping /var/www/projects/project/ eingetragen werden.

Server settings for Remote Debugging

2. Aktivierung von "Listen PHP Connections"

Ich möchte hier nur das Remote Debugging mit der Option "Listen PHP Connections" vorstellen. Bei diesem Verfahren hört PHPStorm quasi die ganze Zeit, ob sich auf Port 9000 etwas tut und schaltet sich ggf. in die Debugger-Steuerung ein.

Um dieses Verfahren zu aktivieren reicht es aus, auf das entsprechende Symbol in der PHPStorm Menüleiste zu klicken oder über das Menü Run > Start Listen PHP Debug Connections zu aktivieren:

Aktivierung des PHP Debuggings im "Listen PHP Debug Connections" Modus

3. Verwendung des Debuggers

Nachdem alles wie beschrieben eingerichtet wurde, kann der Debugger verwendet werden. Dazu kann in einem beliebigen Browser eine URL aus dem zu-debuggenden Projekt aufgerufen werden. Wenn alles klappt, schaltet sich PHPStorm mit einem gesetzten Breakpoint an der entsprechenden Stelle ein:

PHPStorm im Debug Modus mit gesetztem Breakpoint

Problemlösungen

Die folgenden Zeilen lassen erahnen, wie lange und mit welchen Mitteln ich zunächst gesucht habe, als nichts funktioniert hat. Um anderen diese Umstände zu ersparen möchte ich hier ein paar Tipps fürs Troubleshooting geben.

TCP-Dump anschauen

Um zu sehen, ob sich XDebug überhaupt in einen Request einklinkt, ist es hilfreich, mit tcpdump anzuschauen, was über die Leitung geht (ich gehe davon aus, dass der Befehl auf dem Webserver ausgeführt wird):

tcpdump -ni eth1 -n port 9000 -X

gibt den Verkehr auf Port 9000 in beide Richtungen aus,

tcpdump -ni eth1 -n src port 9000 -X

gibt den Verkehr auf Port 9000 von Client (IDE) zu Server (XDebug) aus,

tcpdump -ni eth1 -n dst port 9000 -X

gibt den Verkehr auf Port 9000 von Server (XDebug) zu Client (IDE) aus.

Logfiles anlegen

Mit der oben beschrieben Konfiguration kann XDebug dazu veranlasst werden, ein logfile mit dem gesamten Datenverkehr zwischen Client und Server zu schreiben. Der Datenverkehr besteht übrigens netterweise aus XML und kann deswegen recht gut gelesen werden.

php-info überprüfen lassen

Unter [3] gibt es ein Web-Tool, welches für einen übermittelten php-info dump eventuelle Konfigurationsprobleme mit XDebug ausgibt. Hier habe ich auch den Fehler in meiner Konfiguration gefunden.

path-mappings überprüfen

Mir selber ist es nicht passiert, aber ich hab gelesen, dass mit falschen path-mappings auch nix geht (wen wundert's?). Zur Vollständigkeit sei dieses Problem an dieser Stelle aber noch mal erwähnt!


 
Inhalt © Michael Knoll 2009-2016  •  Powered by TYPO3  •  TypoScript Blogging by Fabrizio Branca  •  TYPO3 Photo Gallery Management by yag  •  Impressum