debug_print_backtrace()

Einführung

Wenn ein PHP-Skript auf einen Fehler trifft, reicht es nicht immer zu wissen, wo er aufgetreten ist — Sie müssen auch wissen, wie das Skript dorthin gelangt ist: welche Funktion welche aufgerufen hat und in welcher Reihenfolge. Diese Kette von Aufrufen ist der Call-Stack, und debug_print_backtrace() gibt ihn fertig formatiert direkt in die Ausgabe aus. Es ist die schnellste Möglichkeit, die Frage „Welcher Pfad hat zu dieser Zeile geführt?" zu beantworten, ohne einen vollwertigen Debugger wie Xdebug einzurichten.

Dieses Kapitel behandelt, was die Funktion tut, ihre Parameter, wie man ihre Ausgabe liest, wann man sie einsetzen sollte und wie sie sich von ihrer Schwester-Funktion debug_backtrace() unterscheidet.

Was debug_print_backtrace() tut

debug_print_backtrace() durchläuft den aktuellen Call-Stack — jeden aktiven Funktions- oder Methodenaufruf vom Skript-Einstiegspunkt bis zu der Stelle, an der Sie die Funktion aufgerufen haben — und gibt einen menschenlesbaren Trace aus. Im Unterschied zu debug_backtrace(), das den Stack als array zurückgibt, damit Sie ihn inspizieren oder protokollieren können, schreibt debug_print_backtrace() den formatierten Text direkt in die Standardausgabe und gibt nichts zurück (void).

Verwenden Sie die Funktion, wenn Sie den Aufrufpfad sofort sehen möchten. Nutzen Sie debug_backtrace(), wenn Sie den Stack verarbeiten müssen (Frames filtern, speichern, an einen Logger senden).

Syntax

debug_print_backtrace(int $options = 0, int $limit = 0): void

Beide Parameter sind optional:

• $options — eine Bitmaske, die die Ausgabe anpasst. Das einzige Flag ist DEBUG_BACKTRACE_IGNORE_ARGS, das die ["params"] (Funktionsargumente) aus jedem Frame weglässt. Die Übergabe von 0 (Standard) schließt Argumentzusammenfassungen ein.
• $limit — begrenzt die Anzahl der ausgegebenen Stack-Frames. 0 (Standard) bedeutet keine Begrenzung. Nützlich bei tiefer Rekursion, wenn nur die wenigen jüngsten Aufrufe von Interesse sind. Verfügbar seit PHP 5.4.0.

Grundlegende Verwendung

Rufen Sie die Funktion von einer beliebigen Stelle in Ihrem Skript auf. Betrachten Sie drei Funktionen, die nacheinander aufgerufen werden:

<?php
function a()
{
    b();
}

function b()
{
    c();
}

function c()
{
    debug_print_backtrace();
}

a();
?>

Hier ruft a() die Funktion b() auf, b() ruft c() auf und c() ruft debug_print_backtrace() auf. Die Ausgabe ist eine nummerierte Liste, der jüngste Aufruf zuerst:

#0 /path/to/script.php(9): c()
#1 /path/to/script.php(4): b()
#2 /path/to/script.php(17): a()

Lesen Sie sie von oben nach unten als „innerster bis äußerster Frame": Frame #0 zeigt, wo c() ausgeführt wurde (Zeile 9), #1 ist der Aufrufer b() (Zeile 4) und #2 ist die ursprüngliche Aufrufstelle a() (Zeile 17). Jede Zeile zeigt die Datei, die Zeilennummer in Klammern und die ausgeführte Funktion. Der Skript-Einstiegspunkt selbst wird nicht als Frame aufgeführt, da er keinen Aufrufer hat.

Anzahl der Frames begrenzen

In rekursivem oder tief verschachteltem Code kann der Trace sehr lang werden. Übergeben Sie ein $limit, um nur die nächstgelegenen Frames zu behalten:

<?php
function countdown($n)
{
    if ($n === 2) {
        // Print just the two nearest frames.
        debug_print_backtrace(0, 2);
        return;
    }
    countdown($n - 1);
}

countdown(5);
?>

Es werden nur zwei Frames ausgegeben, obwohl countdown() mehrfach rekursiv aufgerufen wurde:

#0 /path/to/script.php(9): countdown(2)
#1 /path/to/script.php(9): countdown(3)

Argumente ausblenden

Standardmäßig zeigt jeder Frame eine Zusammenfassung der übergebenen Argumente (wie oben bei countdown(2) zu sehen). Für sensible Daten — Passwörter, Tokens — oder einfach um das Rauschen zu reduzieren, übergeben Sie DEBUG_BACKTRACE_IGNORE_ARGS:

<?php
function login($user, $password)
{
    debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
}

login('admin', 'secret');
?>

Der Frame erscheint weiterhin, aber das Passwort wird nicht mehr in den Trace ausgegeben:

#0 /path/to/script.php(7): login()

Wann man die Funktion einsetzen sollte

• Unerwartete Aufrufe nachverfolgen — eine Methode wird ausgeführt, ohne dass Sie es erwartet haben; fügen Sie einen Backtrace am Anfang ein, um zu sehen, wer sie ausgelöst hat.
• Legacy-Code verstehen — den Aufruffluss schnell abbilden, ohne einen Debugger zu durchlaufen.
• Kontext bei Fehlern protokollieren — für die Protokollierung ist jedoch debug_backtrace() vorzuziehen, damit der Stack als string erfasst und in eine Datei geleitet werden kann (siehe Hinweis unten).

Fallstricke

• Die Funktion gibt aus, sie gibt nichts zurück. Das Ergebnis kann keiner Variable zugewiesen werden. Wenn Sie den Stack für die Protokollierung benötigen, verwenden Sie stattdessen debug_backtrace().
• Die Ausgabe geht in die Antwort. Bei einer Web-Anfrage landet der Trace in der Seitenausgabe (oder im Browser), was HTML oder JSON korrumpieren kann. Entfernen Sie diese Aufrufe vor dem Produktiveinsatz — oder nutzen Sie eine logging-freundliche Alternative.
• Als string erfassen. Wenn Sie die Formatierung von debug_print_backtrace() in einem Log benötigen, können Sie sie mit Output-Buffering abfangen:

<?php
function handler()
{
    ob_start();
    debug_print_backtrace();
    $trace = ob_get_clean();
    // $trace now holds the formatted backtrace as a string.
    error_log($trace);
}

handler();
?>

Verwandte Funktionen

• debug_backtrace() — gibt den Call-Stack als array zurück, anstatt ihn auszugeben.
• var_dump() und print_r() — inspizieren die Werte von Variablen beim Debuggen.
• error_reporting() — steuert, welche Fehler PHP überhaupt meldet.

Fazit

debug_print_backtrace() ist eine einzeilige Möglichkeit, die Kette der Funktionsaufrufe auszugeben, die zum aktuellen Punkt in einem PHP-Skript geführt haben. Die optionalen Parameter $options und $limit ermöglichen es, Argumente auszublenden und lange Traces zu kürzen. Beachten Sie, dass die Funktion ausgibt statt zurückzugeben — für den programmatischen Zugriff auf den Stack nutzen Sie debug_backtrace(), und entfernen Sie print-basierte Traces vor dem Einsatz in der Produktion.

Übungen