Wie Sie das Xdebug-Modul in ServBay aktivieren und konfigurieren

ServBay ist eine leistungsfähige lokale Webentwicklungsumgebung, die Xdebug für PHP-Entwickler bereits vorinstalliert und integriert. Die Aktivierung von Xdebug erhöht deutlich die Effizienz bei der PHP-Entwicklung: Sie können einfacher Debuggen, Performance-Analysen durchführen und die Code Coverage messen. In diesem Leitfaden erfahren Sie Schritt für Schritt, wie Sie Xdebug in ServBay aktivieren und konfigurieren sowie in gängigen Entwicklungsumgebungen (IDEs) integrieren.

Überblick über das Xdebug-Modul

Xdebug ist eine funktionsreiche PHP-Erweiterung, die speziell für das Debuggen und Analysieren von PHP-Code entwickelt wurde. Dank der Vorintegration mit ServBay entfällt für Entwickler der umständliche manuelle Installations- und Kompilierungsprozess – die Aktivierung und Konfiguration von Xdebug ist damit besonders einfach.

Hauptfunktionen von Xdebug

• Breakpoint-Debugging: Sie können Haltepunkte im Code setzen. Bei Erreichen eines Haltepunkts wird die Ausführung angehalten, sodass Sie Variableninhalte und den Aufruf-Stack inspizieren und Ihren Code schrittweise ausführen können.
• Step-Debugging: Unterstützt das Ausführen von Code Schritt für Schritt (Step Over), das Hineinspringen in Funktionen (Step Into) und das Verlassen von Funktionen (Step Out) – ideal, um den Ablauf Ihres Programms nachzuvollziehen.
• Überwachung von Variablen: Während des Debuggings können Sie jederzeit die Werte von lokalen und globalen Variablen beobachten.
• Stack-Trace: Bei Fehlern oder Ausnahmen zeigt Xdebug detaillierte Funktionsaufruf-Stacks an – hilfreich, um Fehlerquellen schnell zu identifizieren.
• Performance-Analyse (Profiling): Erstellt Berichte zur Codeausführung und hilft dabei, Engpässe im Code zu finden.
• Code Coverage-Analyse: Misst den Anteil des Programmcodes, der durch Tests abgedeckt wird – ein wichtiger Wert für die Qualitätssicherung.

In ServBay integrierte Xdebug-Versionen und Portzuordnung

ServBay installiert automatisch jeweils passende Xdebug-Module zu jeder PHP-Version. Dabei erhält jede PHP-Version einen eigenen, eindeutig zugeordneten Debug-Port. Diese getrennte Portzuordnung ist wichtig für die IDE-Konfiguration Ihres Debuggers.

PHP-Version	Vorgebundelte Xdebug-Version	Standard Xdebug-Port
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Port-Regel

Die Standardport-Regel von Xdebug in ServBay lautet 39000 + PHP-Untertversionsnummer. Zum Beispiel: Für PHP 8.3 ergibt das den Port 39000 + 83 = 39083, für PHP 7.4 ist es 39000 + 74 = 39074. Mit dieser Regel finden Sie schnell den Xdebug-Port für jede PHP-Version.

So aktivieren Sie das Xdebug-Modul

Die Aktivierung des Xdebug-Moduls in ServBay ist besonders komfortabel über die grafische Benutzeroberfläche (GUI) möglich. Alternativ können Sie die Konfigurationsdateien auch manuell bearbeiten.

Xdebug über die ServBay-GUI aktivieren

Das ist der einfachste und schnellste Weg:

1. Öffnen Sie die ServBay-Anwendung.
2. Wählen Sie in der linken Seitenleiste den Bereich Sprache (Languages) aus.
3. Klappen Sie den Bereich PHP aus und suchen Sie die PHP-Version, bei der Sie Xdebug aktivieren möchten, z. B. PHP 8.3.
4. Klicken Sie rechts neben der gewünschten Version auf den Button Erweiterungen.
5. Suchen Sie in der angezeigten Erweiterungsliste das Modul Xdebug.
6. Schalten Sie den Schalter links neben Xdebug von „Aus“ auf „An“.
7. Passen Sie die Parameter nach Bedarf an.
8. Klicken Sie unten auf den Button Speichern.
9. ServBay startet den entsprechenden PHP-Prozess automatisch neu und lädt das Modul.

Abbildung: Aktivierung von Xdebug unter „Erweiterungen“

Überprüfen, ob das Xdebug-Modul geladen ist

Am verlässlichsten überprüfen Sie die Aktivierung von Xdebug mithilfe der PHP-Funktion phpinfo():

1. Erstellen Sie im Web-Root von ServBay (Standard: /Applications/ServBay/www) eine Datei wie phpinfo.php.
2. Fügen Sie in phpinfo.php folgenden Inhalt ein:

   <?php
   phpinfo();
   ?>

3. Öffnen Sie die Datei im Browser, zum Beispiel https://servbay.demo/phpinfo.php (ersetzen Sie servbay.demo ggf. durch Ihren konfigurierten Domainnamen).
4. Suchen Sie auf der ausgegebenen phpinfo-Seite nach "Xdebug". Wenn Xdebug erfolgreich geladen ist, finden Sie einen eigenen "Xdebug"-Abschnitt mit Versionsnummer und Konfigurationsparametern.

Abbildung: Xdebug-Informationen in der phpinfo-Ausgabe

Xdebug-Debugging in der IDE einrichten

Die Aktivierung von Xdebug ist der erste Schritt. Für Breakpoint-Debugging in Ihrer IDE müssen Sie nicht nur den PHP-Interpreter, sondern auch den Debugger und die Serverzuordnung korrekt einrichten. Hier finden Sie die wichtigsten Schritte am Beispiel von PHPStorm und Visual Studio Code (VS Code).

Xdebug in PHPStorm einrichten

PHPStorm bietet eine erstklassige Integration von Xdebug.

1. Öffnen Sie die Einstellungen: Starten Sie PHPStorm und öffnen Sie die Einstellungen über das Menü Datei -> Einstellungen (Windows/Linux) oder PHPStorm -> Einstellungen (macOS).

2. PHP CLI-Interpreter konfigurieren:

   • Navigieren Sie zu Sprachen & Frameworks -> PHP.
   • Klicken Sie rechts bei CLI Interpreter auf das ...-Symbol.
   • Im Pop-up-Fenster klicken Sie auf das +, um einen neuen lokalen Interpreter hinzuzufügen.
   • Wählen Sie den Pfad der ausführbaren PHP-Datei der gewünschten ServBay-PHP-Version, z. B. /Applications/ServBay/package/php/8.3/8.3.7/bin/php (Achten Sie auf die korrekten Versionsnummern entsprechend Ihrer Installation).
   • PHPStorm erkennt automatisch Version und Erweiterungen, einschließlich Xdebug.
   • Klicken Sie auf OK zum Speichern. Abbildung: Konfiguration des PHP CLI-Interpreters in PHPStorm für ServBay

3. Xdebug-Debug-Parameter einstellen:

   • Navigieren Sie zu Sprachen & Frameworks -> PHP -> Debug.
   • Stellen Sie bei Xdebug den Debug Port auf den der gewählten PHP-Version entsprechenden Xdebug-Port in ServBay ein (z. B. für PHP 8.3: 39083). Achten Sie darauf, dass dieser Port mit xdebug.client_port übereinstimmt.
   • Aktivieren Sie die Option Can accept external connections.
   • Klicken Sie auf Übernehmen und dann auf OK. Abbildung: Einstellung des Xdebug-Ports in PHPStorm

4. PHP-Webserver-Zuordnung konfigurieren:

   • Gehen Sie zu Sprachen & Frameworks -> PHP -> Server.
   • Klicken Sie rechts auf das +, um einen neuen Server anzulegen.
   • Vergeben Sie einen Servernamen (z. B. ServBay Localhost).
   • Tragen Sie unter Host den Domainnamen ein, den Sie in ServBay eingestellt haben (z. B. servbay.demo).
   • Geben Sie den Port Ihrer Website an, meistens 443 (HTTPS) oder 80 (HTTP).
   • Wählen Sie als Debugger Xdebug.
   • Aktivieren Sie Use path mappings.
   • Ordnen Sie den lokalen Projektpfad (Absoluter Pfad der lokalen Quelle) dem Serverpfad (Absoluter Pfad auf dem Server) zu. Liegt Ihr Projekt z. B. unter /Applications/ServBay/www/myproject und ist über https://servbay.demo/ erreichbar, dann muss /Applications/ServBay/www/myproject auf / gemappt werden. Analog dazu passen Sie die Pfade an, falls Ihr Projekt etwa über eine Subdomain wie https://myproject.servbay.demo/ läuft.
   • Speichern Sie mit OK. Abbildung: Server- und Pfad-Mappings in PHPStorm konfigurieren

5. Debugging starten:

   • Öffnen Sie die relevante PHP-Datei in Ihrem Projekt.
   • Setzen Sie einen Breakpoint, indem Sie links neben der Zeilennummer klicken (roter Punkt).
   • Klicken Sie im oberen PHPStorm-Toolbar auf „Start Listening for PHP Debug Connections“ (Käfersymbol). Wenn das Symbol grün wird, ist PHPStorm bereit, Xdebug-Verbindungen anzunehmen.
   • Öffnen Sie Ihre PHP-Anwendung im Browser (z. B. https://servbay.demo/index.php).
   • Mit korrekter Konfiguration verbindet sich Xdebug automatisch mit PHPStorm – die Ausführung stoppt an Ihren Breakpoints und Sie können direkt debuggen. Abbildung: Aktivieren des Xdebug-Listeners in PHPStorm

Xdebug in Visual Studio Code (VS Code) einrichten

Auch VS Code ist dank passender Erweiterungen eine beliebte Umgebung für das Debugging mit Xdebug.

1. PHP Debug Erweiterung installieren:

   • Öffnen Sie VS Code.
   • Wechseln Sie zur Erweiterungsansicht (Strg+Shift+X bzw. Cmd+Shift+X).
   • Suchen Sie nach "PHP Debug" und installieren Sie die Erweiterung von Felix Becker.

2. launch.json konfigurieren:

   • Öffnen Sie den Ordner Ihres PHP-Projekt.
   • Gehen Sie zur Run & Debug-Ansicht (Strg+Shift+D oder Cmd+Shift+D).
   • Klicken Sie oben auf das Zahnradsymbol und wählen Sie "PHP". Dadurch wird in .vscode im Projektverzeichnis eine launch.json erzeugt.
   • Bearbeiten Sie die launch.json – insbesondere die Konfiguration "Listen for Xdebug". Stellen Sie sicher, dass das Feld port exakt den für Ihre ServBay-PHP-Version konfigurierten Xdebug-Port übernimmt (z. B. für PHP 8.3: 39083).
   • Pfad-Mappings einrichten: Dies ist für korrektes Debugging in VS Code entscheidend. Ergänzen oder bearbeiten Sie in der "Listen for Xdebug"-Konfiguration das Feld pathMappings, sodass die Server-Pfade denen auf Ihrem Rechner entsprechen.

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // Passen Sie diesen Port an Ihre PHP-Version an!
                 "pathMappings": {
                     // ServBay-Root-Pfad auf lokalen Workspace mappen
                     // Beispiel: Projektpfad /Applications/ServBay/www/myproject
                     // erreichbar unter https://servbay.demo/ → '/' zeigt auf Ihr lokales Projektverzeichnis
                     "/": "${workspaceRoot}"
                     // Gleiches gilt für Subdomains auf eigenen Projektverzeichnissen
                     // "/": "${workspaceRoot}" // ebenfalls gültig
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // Passen Sie diesen Port ebenfalls an!
             }
         ]
     }

     Stimmen Sie pathMappings auf Ihre Projektstruktur und die ServBay-Webseiteneinstellung ab. ${workspaceRoot} ist dabei Ihr geöffnetes Projektverzeichnis in VS Code.

3. Debug-Session starten:

   • Öffnen Sie die entsprechende PHP-Datei in VS Code.
   • Klicken Sie links neben die Codezeile, um einen Breakpoint zu setzen (roter Punkt).
   • Wechseln Sie in die Run & Debug-Ansicht (Strg+Shift+D oder Cmd+Shift+D).
   • Wählen Sie oben im Debug-Menü die Konfiguration "Listen for Xdebug".
   • Starten Sie das Debugging mit dem grünen Button. Die VS Code-Statusleiste wird orange und signalisiert, dass auf Xdebug-Verbindungen gewartet wird.
   • Rufen Sie Ihr PHP-Projekt im Browser auf. Bei korrekter Konfiguration stoppt Xdebug an Ihren Breakpoints und Sie können den Code analysieren.

Häufige Fragen (FAQ)

• Q: Der Xdebug-Abschnitt taucht nicht in der phpinfo()-Ausgabe auf?

  • A: Prüfen Sie, ob Xdebug in der ServBay-GUI oder gegebenenfalls in der xdebug.ini aktiviert wurde.
  • Starten Sie den entsprechenden PHP-Dienst neu.
  • Prüfen Sie, ob der Pfad zur xdebug.ini korrekt ist und ob der Eintrag zend_extension = xdebug.so aktiviert ist.
  • Werfen Sie einen Blick in die ServBay-Logdateien (/Applications/ServBay/logs/php/<version>/error.log) auf eventuelle Ladefehler für Xdebug.

• Q: Das Programm hält beim Breakpoint in der IDE nicht an?

  • A: Stellen Sie sicher, dass Ihre IDE auf Xdebug-Verbindungen wartet (Käfersymbol in PHPStorm ist grün, Statusleiste in VS Code ist orange).
  • Prüfen Sie, ob der konfigurierte Xdebug-Port in Ihrer IDE dem xdebug.client_port und dem für Ihre PHP-Version vorgesehenen ServBay-Port entspricht.
  • Überprüfen Sie die Pfad-Mappings in Ihrer IDE. Viele Fehler entstehen durch falsche Zuordnung von lokalen und Server-Dateipfaden!
  • Prüfen Sie etwaige Firewall-Regeln – der jeweilige Xdebug-Port (390xx-Reihe) muss erreichbar sein.
  • Falls xdebug.start_with_request=trigger gesetzt ist, stellen Sie sicher, dass Sie im Browser/Request einen Trigger verwenden (z. B. Browser-Xdebug-Helper-Extension oder ?XDEBUG_TRIGGER=1 in der URL).

• Q: Die Xdebug-Verbindung ist nach einiger Zeit abgebrochen?

  • A: Prüfen Sie die xdebug.ini auf Parameter wie xdebug.remote_autostart bzw. xdebug.start_with_request. Dauerhaftes Aktivieren (yes) kann zu häufigen Verbindungen führen – meist ist der Modus trigger zu empfehlen.
  • Prüfen Sie auch die Debug-Einstellungen Ihrer IDE auf eine mögliche Verbindungs-Timeout-Einschränkung.

Fazit

Mit ServBay und Xdebug steht PHP-Entwicklern ein vorintegriertes, leicht konfigurierbares Debugging-Werkzeug zur Verfügung. Egal ob Sie die komfortable GUI nutzen oder per Hand Dateien anpassen – Sie können Xdebug in unterschiedlichen PHP-Versionen schnell und einfach aktivieren. Zusammen mit den Funktionen moderner IDEs wie PHPStorm oder VS Code schaffen Sie leistungsstarke Debugging-, Performance- und Qualitätssicherungs-Workflows für Ihre PHP-Projekte. Die Kombination von ServBay und Xdebug wird damit zu einem unverzichtbaren Bestandteil einer effizienten lokalen PHP-Entwicklung.