Debugging von PHP-Projekten mit XDebug

XDebug ist ein leistungsstarkes Tool zum Debugging, zur Leistungsanalyse und zur Codeabdeckungsprüfung in der PHP-Entwicklung. Die Integration und Nutzung von XDebug in der lokalen ServBay-Entwicklungsumgebung kann die Effizienz bei der Entwicklung und die Codequalität Ihrer PHP-Projekte erheblich verbessern. Mit XDebug können Entwickler Breakpoints setzen, Variablenwerte prüfen, den Funktionsaufruf-Stack verfolgen, Performance-Engpässe analysieren und Fehler schneller finden und beheben.

Was ist XDebug?

XDebug ist eine für PHP entwickelte Erweiterung, die umfangreiche Debugging- und Analysefunktionen bereitstellt. Sie unterstützt Remote-Debugging (meist über das DBGp-Protokoll), Breakpoints, Single-Stepping, Variableninspektion, Call Stack-Tracing, Performance-Profiling sowie das Erstellen von Code Coverage Reports. So erhalten Entwickler tiefe Einblicke in den Programmablauf und -zustand und können Probleme gezielt und effizient ausfindig machen und lösen.

XDebug bietet verschiedene Betriebsmodi, wobei der Modus debug am häufigsten genutzt wird. Er ermöglicht interaktives Debugging mit Breakpoints.

XDebug in ServBay aktivieren und konfigurieren

ServBay liefert XDebug für jede unterstützte PHP-Version bereits vorinstalliert aus. Sie müssen es weder manuell herunterladen noch kompilieren.

1. XDebug-Modul aktivieren: Öffnen Sie die ServBay-App. Navigieren Sie zu Sprache-PHP und wählen Sie die PHP-Version aus, in der Sie XDebug nutzen wollen. Suchen Sie unter Erweiterungen nach dem Modul xdebug und stellen Sie sicher, dass es aktiviert ist. Falls nicht, aktivieren Sie es per Klick. Danach muss ggf. der PHP-FPM-Dienst neu gestartet werden (ServBay übernimmt dies in der Regel automatisch).

2. IDE konfigurieren: Richten Sie die Verbindung zu XDebug in Ihrer bevorzugten IDE, wie PHPStorm oder VS Code, ein. Meistens geht es um die Port-Konfiguration (sie muss mit den XDebug-Einstellungen in der UI übereinstimmen) und ein mögliches Mapping von lokalen zu Server-Pfaden (dies ist in ServBay lokal üblicherweise nicht nötig).

   Weitere Details zur IDE-Konfiguration

   Ausführliche Schritt-für-Schritt-Anleitungen zur Konfiguration von XDebug in bestimmten IDEs wie PHPStorm oder VS Code finden Sie in der jeweiligen IDE-Dokumentation oder in unserem Beitrag Wie Sie das mitgelieferte XDebug-Modul in ServBay aktivieren.

Praxisbeispiel: PHP-Projekt mit XDebug in ServBay debuggen

Mit folgendem Beispielprojekt zeigen wir, wie Sie XDebug in ServBay zum Debuggen einsetzen können.

1. ServBay-Website einrichten

Zunächst legen Sie eine neue Website in ServBay an, um das Beispiel-Projekt zu hosten:

1. Erstellen Sie im ServBay-Web-Root-Verzeichnis /Applications/ServBay/www/ einen neuen Projektordner, z.B. servbay-xdebug-app.
2. Öffnen Sie die ServBay-App und gehen Sie zum Bereich „Websites“.
3. Klicken Sie auf „Neue Website hinzufügen“ und geben Sie als Root-Verzeichnis /Applications/ServBay/www/servbay-xdebug-app an.
4. Richten Sie eine lokale Domain ein, z.B. servbay-xdebug-app.servbay.demo.
5. Wählen Sie Ihre gewünschte PHP-Version aus und stellen Sie sicher, dass wie oben beschrieben XDebug aktiviert und konfiguriert wurde.
6. Speichern und übernehmen Sie die Änderungen. ServBay konfiguriert Caddy/Nginx sowie die Hosts-Datei (oder verwendet den OS-internen DNS-Service) automatisch.

2. Projektstruktur und Beispielcode

Legen Sie im Verzeichnis /Applications/ServBay/www/servbay-xdebug-app/ folgende Ordner und Dateien an:

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

Der Inhalt von src/Calculator.php:

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // Setzen Sie hier einen Breakpoint
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

Der Inhalt von index.php:

<?php
// Angenommen, Sie nutzen Composer, wird hier der Autoloader geladen
// Falls Sie keinen Composer verwenden, passen Sie den Ladevorgang entsprechend an
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Debugging Example:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Sum: " . $sum . "\n";
echo "Difference: " . $difference . "\n";

echo "Done.\n";
?>

Hinweis: Die Zeile require __DIR__ . '/vendor/autoload.php'; geht davon aus, dass Sie Composer verwenden. Für einen einfachen Test können Sie diese Zeile entfernen und use App\Calculator; durch require __DIR__ . '/src/Calculator.php'; ersetzen.

3. Breakpoint setzen

Öffnen Sie in Ihrer IDE (z.B. PHPStorm) die Datei /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php und klicken Sie links neben die Zeilennummer der Zeile return $a + $b; im add-Methode, um einen Breakpoint zu setzen.

4. Debugging-Session starten

1. Aktivieren Sie in Ihrer IDE das Listening für XDebug-Verbindungen. In PHPStorm klicken Sie dazu meist auf den „Start Listening for PHP Debug Connections“-Button (Telefonhörer- oder Käfer-Symbol) in der Toolbar.
2. Rufen Sie die index.php Ihres ServBay-Projekts im Browser auf: https://servbay-xdebug-app.servbay.demo/index.php.
3. Haben Sie die XDebug-Einstellung xdebug.start_with_request auf trigger gesetzt? Dann stellen Sie sicher, dass Sie über eine Browser-Erweiterung oder per Hand einen XDebug-Trigger hinzufügen (z.B. mittels https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Debugging-Ablauf

1. Sobald Sie die index.php im Browser aufrufen und XDebug getriggert ist, verbindet sich XDebug automatisch mit Ihrer IDE und hält die Ausführung am gesetzten Breakpoint an.
2. Die IDE wechselt in den Debug-Modus und zeigt Ihnen, dass die Ausführung in der Methode add in Calculator.php pausiert wurde.

6. Variablen prüfen

1. Im Debug-Fenster der IDE sehen Sie die aktuelle Codezeile, den Call Stack (Funktionsaufruf-Stack), die Variablen usw.
2. Im „Variables“-Panel können Sie alle aktuellen Variablen einsehen. Zum Beispiel sollten $a den Wert 5 und $b den Wert 3 haben.

7. Schrittweises Debugging

1. Nutzen Sie die Steuerschaltflächen Ihrer IDE für das Single-Stepping (meistens Step Over (F8), Step Into (F7), Step Out (Shift+F8) usw.).
   • Step Over: Führt die aktuelle Zeile aus, ohne in Funktionsaufrufe hineinzuspringen – die Ausführung geht danach zur nächsten Zeile weiter.
   • Step Into: Springt bei Funktionsaufrufen in die erste Zeile der Funktion hinein.
   • Step Out: Führt die aktuelle Funktion zum Ende aus und springt dann zurück zur aufrufenden Stelle.
2. Mit Single-Stepping können Sie Zeile für Zeile den Ablauf sowie die Werte der Variablen genau beobachten.

8. Fortsetzen der Ausführung

1. Klicken Sie in der IDE auf „Resume Program“ (meistens grünes Play-Icon oder F9). Das Programm läuft weiter, bis der nächste Breakpoint erreicht wird oder der Code vollständig ausgeführt ist.

9. Ausgabe prüfen

1. Nach Abschluss der Programmausführung können Sie die Ausgaben entweder im Browser (oder bei CLI-Skripten im Terminal) sehen. Im Beispiel lautet die Ausgabe:

   Debugging Example:
   Sum: 8
   Difference: 2
   Done.

Hinweise

• Firewall: Stellen Sie sicher, dass Ihr Betriebssystem keine eingehenden Verbindungen auf dem von Ihrer IDE genutzten Port (Standard ist 9003) blockiert.
• Port-Konflikte: Der für XDebug verwendete Port darf von keiner anderen Anwendung belegt sein.
• Performance: Bei xdebug.mode=debug und xdebug.start_with_request=yes wird für jede PHP-Anfrage Debugging gestartet, was die Seite erheblich verlangsamen kann. Schalten Sie XDebug aus oder stellen Sie xdebug.start_with_request auf trigger, wenn Sie nicht aktiv debuggen.
• CLI-Debugging: XDebug kann auch zum Debugging von PHP-CLI-Skripten verwendet werden. Sie müssen hierfür ggf. Umgebungsvariablen setzen oder bestimmte Parameter verwenden. Details finden Sie in der offiziellen XDebug-Dokumentation.
• IDE-Version und Konfiguration: Die Konfigurationsoberflächen und -optionen können je nach IDE-Version leicht variieren. Nutzen Sie die offizielle Dokumentation Ihrer IDE für die zielgerichtete Einrichtung.

FAQ – Häufige Fragen zur Fehlerbehebung

F: Meine IDE kann keine Verbindung zu XDebug herstellen. Was kann ich tun?

A: Prüfen Sie bitte Folgendes:

1. Ist das XDebug-Modul für die verwendete PHP-Version in ServBay aktiviert?
2. Sind die Einstellungen in Ihrer php.ini für xdebug.mode, xdebug.client_host, xdebug.client_port korrekt? Stimmen client_host und client_port mit den Listening-Einstellungen der IDE überein?
3. Verwenden Sie xdebug.start_with_request = trigger? Haben Sie den Trigger korrekt gesetzt (GET/POST-Parameter, Cookie oder Header)?
4. Lassen Ihre Firewall-Einstellungen den Datenverkehr auf dem XDebug-Port durch?
5. Lauscht Ihre IDE tatsächlich auf den festgelegten Port?

F: Warum lädt meine Website nach Aktivierung von XDebug plötzlich extrem langsam?

A: Sehr wahrscheinlich ist in den XDebug-Einstellungen xdebug.start_with_request auf yes gestellt. So wird für jede Anfrage Debugging initialisiert, was die Performance stark beeinträchtigt. Stellen Sie am besten auf trigger um, sodass Debugging nur manuell ausgelöst wird.

F: Kann ich mit XDebug auch AJAX-Requests debuggen?

A: Ja! AJAX-Debugging funktioniert im Prinzip genauso wie mit normalen HTTP-Requests. Sie müssen dafür sorgen, dass der AJAX-Request einen XDebug-Trigger enthält (das geht z.B. über ein entsprechendes Cookie oder HTTP-Header).

F: Unterstützt ServBay-XDebug neben PHPStorm auch VS Code oder andere IDEs?

A: Ja. Das von ServBay integrierte XDebug ist die Standard-PHP-Erweiterung, die von allen Ide-Editoren und IDEs mit DBGp-Debugging-Protokoll unterstützt wird – darunter VS Code (mit PHP Debug Extension), NetBeans, Eclipse u.a. Die Konfiguration ist größtenteils identisch und betrifft insbesondere den Debugging-Port in der IDE.

Fazit

Dank der in ServBay integrierten XDebug-Erweiterung können Sie Ihre PHP-Projekte besonders effizient und komfortabel im lokalen Umfeld debuggen. Beherrschen Sie Breakpoints, Variablen-Inspektion und Single-Stepping, steigert das signifikant Ihre Fehlerbehebungs- und Analysefähigkeiten sowie die Codequalität. In Verbindung mit ServBays einfach zu verwaltender Entwicklungsumgebung bleibt XDebug ein unverzichtbares Tool in Ihrem PHP-Workflow. Starten Sie jetzt mit XDebug in ServBay durch und erleben Sie eine noch produktivere, reibungslosere PHP-Entwicklung!