Konfigurieren von Xdebug in PHPStorm

Debugging ist einer der wichtigsten Prozesse in der Programmierung. Mit Hilfe eines Debuggers können Sie sehen, was im Programm passiert, welche Funktionen ausgeführt werden, was in Variablen gespeichert ist, sowie alles Schritt für Schritt ausführen und genau verstehen, in welcher Zeile und bei welchen Werten von Variablen ein Fehler auftritt.

Der Xdebug Debugger wird zum Beispiel für PHP verwendet, PHPStorm ist eine der beliebtesten Entwicklungsumgebungen. Als nächstes sehen wir uns an, wie man Xdebug in PhpStorm für das Debugging auf dem lokalen Computer und in Docker konfiguriert.

Konfigurieren von XDEBUG in PHPSTORM

Lassen Sie uns darüber sprechen, wie das Debugging auf dem lokalen Server durchgeführt wird.

Schauen wir uns den gesamten Prozess am Beispiel von Ubuntu und dem mit Apache konfigurierten PHP-Interpreter an. Bei anderen Konfigurationen können die Dateipfade anders sein, aber der Punkt ist derselbe. Mit dem Xdebug-Debugger können Sie die Codeausführung anhalten, den Aufrufstapel und den Inhalt von Variablen einsehen. Sein einziger Nachteil ist, dass es keine komfortable Steuerungsschnittstelle gibt. Normalerweise werden IDEs verwendet, um das Debugging zu verwalten. Aber die IDE kann dem Debugger nicht sagen, dass er mit dem Debuggen beginnen soll, da sie nur für den Code zuständig ist. Zu diesem Zweck benötigen Sie die Browsererweiterung Debug Helper, mit deren Hilfe Sie den Debugging-Modus aktivieren können.

Zuerst müssen Sie Xdebug installieren. Führen Sie dazu Xdebug aus:

$ sudo apt install xdebug

Sobald der Xdebug-Installationsprozess abgeschlossen ist, sollten Sie das Programm so konfigurieren, dass es beim Starten einer Debugging-Sitzung versucht, sich mit unserer IDE zu verbinden, um das Debugging zu steuern. Fügen Sie dazu diese Zeilen in die Datei /etc/php/7.4/apache2/conf.d/20-xdebug.ini in der Version Xdebug 2 ein:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Für eine neuere Version ist es am besten, ein anderes Format zu verwenden:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Schauen wir uns die Einstellungen genauer an. Der erste Parameter xdebug.mode - Debugging-Modus, mögliche Optionen sind:

• develop - ermöglicht die Ausgabe zusätzlicher Informationen, hat Vorrang vor var_dump;

• debug - Modus der zeilenweisen Code-Ausführung, das ist der Modus, den wir in diesem Fall brauchen;

• profile - Profilerstellung;

• trace - Verfolgung der Programmausführung.

Mehrere Modi werden gleichzeitig aktiviert, wenn sie in Kommas aufgeführt sind. Die zweite Zeile xdebug.start_with_request legt fest, wie der Debugger für die Modi debug, trace und ähnliche Modi gestartet werden soll:

• yes - immer, wenn php-Skripte ausgeführt werden;
• no - Start nur bei Code mit speziellen Funktionen;
• trigger - auf Anfrage, unter Verwendung einer speziellen Variable in $_ENV, $_POST, $COOKIE oder einem anderen Array. Diese Option eignet sich in diesem Fall am besten, damit der Debugger nicht läuft, wenn er nicht benötigt wird.

Die dritte Option xdebug.discover_client_host wird auf true gesetzt. In diesem Fall versucht xdebug, sich mit dem im HTTP_X_FORWARDED_FOR-Header übergebenen Host zu verbinden. Da der Host in der nächsten Zeile angegeben wird, ist diese Funktion in diesem Fall nicht erforderlich. Der nächste Client-Host, zu dem eine Verbindung für die Debugging-Kontrolle aufgebaut werden soll, ist 127.0.0.1 und Port 9000. Dies ist der Standardport, der derzeit in PhpStorm verwendet wird. Nachdem Sie die Einstellungen gespeichert haben, müssen Sie den Apache mit einem speziellen Befehl neu starten:

$ sudo systemctl restart apache2

Als nächstes sollten Sie PhpStorm konfigurieren. Starten Sie das Programm und öffnen Sie dann das Menü Ausführen -> Konfigurationen bearbeiten. Es wird ein Fenster angezeigt, in dem Sie den Debugger konfigurieren müssen.

Klicken Sie auf die Schaltfläche + und wählen Sie in der sich öffnenden Liste PHP Remote Debugger aus:

Ändern Sie nichts an den Einstellungen, sondern geben Sie nur den Namen dieser Debugging-Methode an. Wenn Sie den Server, von dem Verbindungen erwartet werden, nicht angeben, werden alle Verbindungen akzeptiert.

Wenn Sie den Port, zu dem Xdebug eine Verbindung herstellt, ändern möchten, öffnen Sie Datei -> Einstellungen -> PHP -> Debug -> DBGp Proxy. Hier können Sie den gewünschten Port angeben.

Wir können sagen, dass die IDE jetzt bereit ist. Klicken Sie nun auf den Fehler in der oberen Symbolleiste. Das Programm wartet nun darauf, dass der Debugger eine Verbindung herstellt, und wir setzen einige Haltepunkte in den Code, indem wir einfach vor die Zeile mit dem Code klicken:

Jetzt muss nur noch der Browser konfiguriert werden.Für Chrome können Sie eine spezielle Erweiterung herunterladen. Installieren Sie sie und öffnen Sie die Seite, die Sie debuggen möchten. Klicken Sie auf das Symbol der Erweiterung und wählen Sie Debuggen. Das Symbol der Erweiterung wird nun grün:

Aktualisieren Sie die Seite und kehren Sie zu PHPStorm zurück. Wenn alles richtig gemacht wurde, wird dort eine Debugging-Sitzung gestartet. Beim ersten Start fordert das Programm Sie möglicherweise auf, die lokalen Dateipfade so zu konfigurieren, dass sie mit den Pfaden der Remote-Dateien übereinstimmen. Für den lokalen Server brauchen Sie hier nichts zu konfigurieren, klicken Sie einfach auf Akzeptieren:

Danach hält der Debugger die Ausführung am ausgewählten Haltepunkt an und die Debugging-Schnittstelle wird im Programm angezeigt:

Jetzt wollen wir verstehen, wie man Xdebug PhpStorm und Docker konfiguriert.

PHP in DOCKER debuggen

Docker kann ein wenig knifflig sein. Da der Debugger sich mit der IDE selbst verbinden muss, müssen Sie den Host an den Container weiterleiten. Unter Windows kann dies über die Adresse host.docker.internal erfolgen. Unter Linux ist dies jedoch nicht standardmäßig der Fall. Um eine solche Adresse hinzuzufügen, müssen Sie die folgenden Zeilen zu docker-compose hinzufügen:

extra_hosts:

host.docker.internal: host-gateway

Wir verwenden die folgende Verzeichnisstruktur:

Die minimal erforderliche docker-compose.yaml sieht wie folgt aus:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Wir deklarieren einfach zwei Container, nginx und php-fpm. Am ersten Container nehmen wir keine Änderungen vor, so dass wir einfach das offizielle Image nehmen, den Quellordner mounten, die Konfigurationsdatei und den Port weiterleiten können. Im zweiten Container ist es notwendig, Xdebug zu installieren und zu konfigurieren, so dass er auf der Basis des offiziellen php-Containers gebaut werden muss. Für denselben Container muss die extra_hosts-Direktive angegeben werden, ohne sie funktioniert nichts. Die Nginx-Konfiguration ist ebenfalls ziemlich standardisiert:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

So konfigurieren Sie die Verarbeitung von PHP-Skripten im php-fpm-Container und leiten nicht existierende URLs auf index.php um, was bei vielen Frameworks und CMS Standard ist. Im Dockerfile des php-fpm-Containers sieht es so aus:

Installieren Sie xdebug mit pecl, und kopieren Sie dann die Konfigurationsdatei in den Container. Datei:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

Xdebug 3 für PHP 8 wird im Container installiert, da die alte Version nicht mehr mit dieser Version der Sprache funktioniert, also wird die neue Konfigurationssyntax verwendet. Nun host, host.docker.internal, was früher in docker-compose.yaml vorgeschrieben war. Die Konfiguration von xdebug PHPStorm docker ist nun abgeschlossen. Als nächstes können Sie das Projekt ausführen:

docker-compose up --build

Jetzt können Sie, wie bei der vorherigen Option, den Debug-Modus im Browser aktivieren, die Seite aktualisieren und der Debugger wird sich erfolgreich mit der IDE verbinden, trotz der Tatsache, dass er in Docker läuft