phpdbg_break_file — Funktion · PHP-Referenz

Signatur

phpdbg_break_file(string $file, int $line): void

Beschreibung

phpdbg_break_file() ermöglicht es, innerhalb eines PHP-Skripts programmatisch einen Breakpoint für den interaktiven Debugger phpdbg zu setzen. Wenn das Skript unter phpdbg ausgeführt wird und die angegebene Zeile in der angegebenen Datei erreicht wird, unterbricht der Debugger die Ausführung und übergibt die Kontrolle an den Benutzer.

Dies ist besonders nützlich, wenn man Breakpoints dynamisch — also abhängig von Laufzeitbedingungen — setzen möchte, anstatt sie statisch in der phpdbg-Konsole einzutragen. So kann beispielsweise ein Breakpoint nur gesetzt werden, wenn eine bestimmte Variable einen unerwarteten Wert annimmt.

Die Funktion hat ausschließlich Auswirkungen, wenn das Skript tatsächlich unter phpdbg läuft. In einer normalen PHP-Umgebung (CLI, FPM, Apache-Modul usw.) ist der Aufruf wirkungslos und erzeugt keinen Fehler.

Neben phpdbg_break_file() existieren verwandte Funktionen wie phpdbg_break_function() und phpdbg_break_method(), die Breakpoints auf Funktions- bzw. Methodenebene setzen können.

Parameter

Name	Typ	Default	Beschreibung
$file Pflicht	string		Der Pfad zur PHP-Datei, in der der Breakpoint gesetzt werden soll. Es empfiehlt sich, einen absoluten Pfad (z. B. via `__FILE__` oder `realpath()`) anzugeben, um Mehrdeutigkeiten zu vermeiden.
$line Pflicht	int		Die Zeilennummer innerhalb der angegebenen Datei, an der die Ausführung unterbrochen werden soll. Die Zählung beginnt bei `1`.

Rückgabewert

Typ

void

Beschreibung

Die Funktion gibt keinen Wert zurück.

Beispiele

Einfacher Breakpoint in der aktuellen Datei

<?php
// Breakpoint in der aktuellen Datei an Zeile 10 setzen
phpdbg_break_file(__FILE__, 10);

$wert = 42;
echo "Wert: " . $wert . PHP_EOL;
// Wenn phpdbg die Zeile 10 erreicht, wird die Ausführung unterbrochen

Bedingter Breakpoint basierend auf einem Laufzeitwert

<?php
function verarbeiteBenutzer(array $benutzer): void
{
    foreach ($benutzer as $eintrag) {
        // Breakpoint nur setzen, wenn ein verdächtiger Wert auftritt
        if ($eintrag['alter'] < 0) {
            phpdbg_break_file(__FILE__, __LINE__ + 1);
        }
        echo "Benutzer: " . $eintrag['name'] . ", Alter: " . $eintrag['alter'] . PHP_EOL;
    }
}

$benutzer = [
    ['name' => 'Anna',  'alter' => 30],
    ['name' => 'Bernd', 'alter' => -5],
    ['name' => 'Clara', 'alter' => 25],
];

verarbeiteBenutzer($benutzer);

// Wichtig · Fallstricke

Nur unter phpdbg wirksam: Wird das Skript nicht unter dem phpdbg-SAPI ausgeführt, hat der Aufruf keinerlei Effekt. Eine Prüfung mit PHP_SAPI === 'phpdbg' kann sinnvoll sein, um unnötige Aufrufe zu vermeiden.

Produktionsumgebung: phpdbg_break_file()-Aufrufe sollten nicht in Produktionscode verbleiben. Obwohl sie außerhalb von phpdbg nichts bewirken, stellen sie toten Code dar und können zu Verwirrung führen.

Die Funktion ist Teil der phpdbg-Erweiterung, die standardmäßig in PHP 5.6+ mitgeliefert wird. In manchen Distributionen kann die Erweiterung jedoch deaktiviert oder nicht vorhanden sein.

Siehe auch

phpdbg_break_function phpdbg_break_method phpdbg_break_next phpdbg_clear phpdbg_exec