Ein How-To wie dein PhpStorm, Homestead-Umgebungen debuggen kann.

Dieses Tutorial ist in Homestead v8, PhpStorm 2020.3 und Xdebug v2.9 gebastelt.

TL;DR

• Setze die Homestead Mappings in PhpStorm unter PHP -> Servers.
• Passe die xdebug.ini’s in Homestead an: Snippet.
• Aktiviere Xdebug via sudo phpenmod xdebug. Falls bereits aktiv deaktiviere (sudo phpdismod xdebug) und aktiviere das Modul erneut.
• Setze einen Haltepunkt, und entweder teste via Browser oder via CLI.
• CLI debuggen: XDEBUG_SESSION_START=PHPSTORM als Umgebungsvariable übergeben.
• Browser debuggen: ?XDEBUG_SESSION_START=PHPSTORM als Query Parameter oder Cookie übergeben.

Motivation

Als ich 2013 aus der .net-Ecke zu PHP kam, hat irgendwie der Debugger gefehlt. Die Klarheit welche Variablen eigentlich wann und wo verfügbar sind.

Und dann stolpere ich über Xdebug. Es sah alles so einfach aus. Na ja, Tage vergingen und Xdebug lief immer noch nicht. Also ließ ich das Thema ruhen.

Jahre vergingen, Erfahrungen gewonnen und irgendwann, finally… konnte auch ich Xdebug aufsetzen. ?

In diesem How-To zeige ich dir einen von vielen Wegen wie du Xdebug in Homestead aufsetzt.

Dafür gehen wir drei Schritte durch:

• Wir konfigurieren PhpStorm so, dass Pfade innerhalb von Homestead richtig erkannt werden.
• Passen die xdebug.ini innerhalb von Homestead an.
• Und aktivieren das PHP-Modul Xdebug innerhalb von Homestead.

Bevor es losgeht brauchen wir etwas Theorie.

Wie Homstead deine Host-Dateien in der Box bereitstellt

Die Homstead.yaml definiert eine Liste folders:. Dort schütten wir Ordner rein, die am Ende im Gast verfügbar sind.

So zum Beispiel:

[...]

folders:
    - map: ~/Projects/spielwiese/spielwiese-website
      to: /home/vagrant/spielwiese/spielwiese-website

[...]

Wenn wir das Beispiel in Deutsch übersetzen, klingt es in etwa:

Hey Homestead stelle mal folgende Ordner im Gast bereit.

Und zwar:
- Der Ordner `spielwiese-website` unter `Home/Projects/spielwiese` soll im Gast unter `Home/spielwiese` erreichbar sein.

Bitte, danke.

Und BAM. Sobald wir eine Verbindung zur Maschine aufbauen, finden wir den Ordner unter /home/vagrant/spielwiese/spielwiese-website.

Merken wir uns:
Irgendwie werden Ordner vom Host zum Gast gemappt. Von wo und wohin können wir in Homestead.yaml nachlesen.

Wenn wir das wissen, kann es loslegen.

PhpStorm PHP Server Pfade anpassen

Homestead liefert PHP, also stellen wir Remote-Verbindungen her. Xdebug kann über Remote-Verbindungen debuggen.

Damit PhpStorm Remote-Verbindungen wirklich versteht, muss es wissen, wo Host-Ordner auf dem Gast-Ordner sind.

Dafür konfigurieren wir einen PHP-Server.

• Öffne PhpStorm.
• Springe in die PHP-Server Einstellungen unter: File -> Settings -> Languages & Frameworks -> PHP -> Servers.
• Klicke auf das + Icon.

• Vergebe einen Namen. Zum Beispiel: spielwiese, oder http://spielwiese.local.test. An sich dient der Name lediglich der Übersicht, also kannst du den Frei wählen.
• Setze den Host. Du kennst den Host nicht? Kein Problem, schau in die Homestead.yaml unter sites:.
• Ändere den Port auf 443, solltest du SSL unter Homestead einsetzen.
• Checke den Punkt Use path mappings {...}.

Daraufhin erscheinen zwei neue Tabs.

Der linke zeigt die Ordner und Dateien deines Host an. Bzw. deines PhpStorm-Projekts.

Im rechten Tab vergeben wir Pfade wo diese Datei im Gast zu finden sind.

Nehmen wir an lokal ~/Projects/spielwiese/spielwiese-website wird im Gast auf /home/vagrant/spielwiese/spielwiese-website, dann sieht deine Konfiguration so aus:

Mit einem Klick auf Apply bestätigen und mit Ok das Einstellungsfenster schließen.

PhpStorm ist nun kampfbereit.

Remote Xdebug-Verbindungen in Homestead konfigurieren

Homestead liefert xdebug.ini’s für jede installierte PHP version.

Mindestens seit Homestead v8 finden wir diese unter /etc/php/{version}/mods-available/xdebug.ini.

Exemplarisch hier die Einstellungen für PHP v7.4.

Falls du andere oder mehrere PHP Versionen im Einsatz hast, bietet es sich an die Schritte für jede Version zu wiederholen.

• Verbinde dich via SSH mit Homestead. (vargant ssh | homestead ssh | …)
• Öffne xdebug.ini in einem Editor deiner Wahl.

sudo vim /etc/php/7.4/mods-available/xdebug.ini

• Entferne die Zeile xdebug.remote_connect_back = 1.
• Paste xdebug.remote_autostart = 1 und xdebug.remote_host = 10.0.2.2.
  Du erwartest etwas Ähnliches wie:

zend_extension=xdebug.so
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = 10.0.2.2
xdebug.remote_port = 9000
xdebug.max_nesting_level = 512

• Speichern und Editor schließen.
• Aktiviere Xdebug mit:

sudo phpenmod xdebug

Falls Xdebug bereits aktiv, deaktiviere und aktiviere das Modul erneut.

sudo phpdismod xdebug

• Verifiziere das Xdebug aktiviert ist:

php --ini | grep xdebug

Daraufhin erhalten wir etwas wie:

PhpStorm, Haltepunkte und debuggen

Um Ressourcen zu sparen, lässt uns PhpStorm entscheiden, ob es auf Debug Verbindungen lauschen darf.

Die Einstellung dazu liegt in der oberen rechten Ecke. Sieht so in etwa so aus:

Klicken wir darauf lauscht PhpStorm auf Debug Verbindungen.

Um PhpStorm über Debug Verbindungen zu benachrichtigen haben wir mindestens zwei Möglichkeiten.

Im Terminal als Umgebungsvariable:

XDEBUG_SESSION_START=PHPSTORM composer {script}

Oder im Browser als Cookie oder auch als Query Parameter.

# Beispiel für https://spielwiese.local.test/baum`
https://spielwiese.local.test/baum?XDEBUG_SESSION_START=PHPSTORM

Das Leben im Browser kann deutlich vereinfacht werden, mit Erweiterungen die automatisch Cookies setzen.

Nun haben wir Dinge konfiguriert und wissen wie PhpStorm anzustoßen um Dinge zu debuggen. Es wird Zeit einen Haltepunkt zu setzen.

Dafür eine PHP Datei öffnen und rechts neben der Zeilennummer einmal klicken.

Es erscheint ein roter Punkt.

Nun im Browser oder Terminal den Haltepunkt anstoßen et voila. Wir erhalten etwas wie:

Performance

So viel Übersicht das Debuggen mit Xdebug und PhpStorm liefert, so kann es bei großen Projekten leicht zu drastischen Zeit einbußen führen.

Daher empfiehlt es sich Xdebug, anstatt es immer Aktiv zu halten, erst dann zu aktivieren, wenn es gebraucht wird. Sobald es nicht mehr gebraucht wird, wieder deaktivieren.