Variablen ausgeben

Jedem, der debuggt, ist die Funktion var_dump vertraut, die ausführliche Informationen über eine Variable ausgibt. Leider fehlt ihrer Ausgabe die HTML-Formatierung, und sie verschmilzt zu einer einzigen Zeile, ganz zu schweigen von den Problemen mit dem HTML-Escaping. In der Praxis ist es nötig, var_dump durch eine bequemere Funktion zu ersetzen. Diese Funktion ist dump().

$arr = [10, 20.2, true, null, 'hello'];

dump($arr);
// oder Debugger::dump($arr);

erzeugt die Ausgabe:

Das standardmäßige helle Theme können Sie auf dunkel umstellen:

Debugger::$dumpTheme = 'dark';

Sie können außerdem die Verschachtelungstiefe über Debugger::$maxDepth, die Länge der angezeigten Strings über Debugger::$maxLength und die Anzahl der angezeigten Array- oder Objektelemente über Debugger::$maxItems ändern. Niedrigere Werte beschleunigen das Rendern natürlich.

Debugger::$maxDepth = 2; // Standard: 15
Debugger::$maxLength = 50; // Standard: 150
Debugger::$maxItems = 50; // Standard: 100

Die Funktion dump() kann außerdem die Stelle anzeigen, an der sie aufgerufen wurde, und bei Objekten den Pfad zur Datei, in der ihre Klasse definiert ist. Das steuert die Property Debugger::$showLocation:

Debugger::$showLocation = true; // zeigt die Ortsangabe an
Debugger::$showLocation = false; // blendet sie aus

Für feinere Kontrolle rufen Sie Tracy\Dumper::dump() direkt auf und übergeben die Option Dumper::LOCATION mit dem Wert Dumper::LOCATION_CLASS (nur die Stellen, an denen Klassen definiert sind) oder Dumper::LOCATION_SOURCE (auch die Stelle, an der dump() aufgerufen wurde).

Praktische Alternativen zu dump() sind dumpe() (dump & exit) und bdump(). Letzteres erlaubt uns, die Werte von Variablen im Panel der Tracy Bar auszugeben. Das ist sehr bequem, denn die Dumps sind vom Layout der Seite getrennt, und wir können ihnen außerdem einen Titel geben.

bdump([2, 4, 6, 8], 'gerade Zahlen bis zehn');
bdump([1, 3, 5, 7, 9], 'ungerade Zahlen bis zehn');

Tracy\Dumper direkt verwenden

Hinter dump() steht die Klasse Tracy\Dumper, die Sie auch direkt verwenden können. Anders als dump() stützt sie sich nicht auf Debugger und nimmt alle ihre Einstellungen aus einem Options-Array entgegen, was sie für eigenständige Skripte, CLI-Werkzeuge oder immer dann praktisch macht, wenn Sie den Dump als String brauchen. Weil die Einstellungen aus dem Array und nicht von Debugger kommen, unterscheiden sich die Standardwerte leicht: Die Tiefe beträgt zum Beispiel 7 statt 15.

Die Methoden geben den Dump als String zurück:

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML für den Browser
$text = Dumper::toText($var);                         // Klartext, z. B. für ein Log
$ansi = Dumper::toTerminal($var);                     // Text mit ANSI-Farben für das Terminal

Oder geben Sie die Variable gleich mit Dumper::dump() aus, das je nach Umgebung automatisch die HTML- oder die Terminal-Ausgabe wählt:

Dumper::dump($var, [Dumper::DEPTH => 3]);

Die HTML-Ausgabe braucht ein kleines Stylesheet und ein Skript. Wenn Sie außerhalb einer Anwendung mit aktivierter Tracy ausgeben (also ohne Debugger::enable()), geben Sie sie einmal im Kopf der Seite mit Dumper::renderAssets() aus. Dumper::dump() erledigt das selbst, toHtml() jedoch nicht.

Optionen

Die Ausgabe wird über ein Options-Array gesteuert, das allen oben genannten Methoden übergeben wird:

Option Beschreibung Standard
Dumper::DEPTH maximale Verschachtelungstiefe 7
Dumper::TRUNCATE maximale Länge von Strings 150
Dumper::ITEMS maximale Anzahl der in einem Array/Objekt angezeigten Elemente 100
Dumper::COLLAPSE den obersten Knoten einklappen? true/false, oder ihn einklappen, sobald er mindestens so viele Elemente hat 14
Dumper::COLLAPSE_COUNT einen verschachtelten Knoten einklappen, sobald er mindestens so viele Elemente hat 7
Dumper::LOCATION die Ortsangabe anzeigen; true/false, oder Dumper::LOCATION_CLASS (nur die Stellen, an denen Klassen definiert sind) oder Dumper::LOCATION_SOURCE (auch die Aufrufstelle) aus
Dumper::THEME Farbschema, light oder dark light
Dumper::HASH IDs von Objekten (die Markierung #) und Referenzen (die Markierung &) anzeigen? true
Dumper::DEBUGINFO die magische Methode __debugInfo() des Objekts verwenden? false
Dumper::KEYS_TO_HIDE Array von Schlüsselnamen, deren Werte als ***** verborgen werden []
Dumper::SCRUBBER Callback fn(string $key, mixed $value, ?string $class): bool, der bei sensiblen Werten true zurückgibt keiner
Dumper::OBJECT_EXPORTERS eigenes Rendern von Objekten, siehe unten []

Die Optionen COLLAPSE, COLLAPSE_COUNT und THEME gelten nur für die interaktive HTML-Ausgabe.

Die Option SCRUBBER verbirgt sensible Werte im Dump; ein vollständiges Beispiel finden Sie unter Eigener Scrubber.

Um zum Beispiel einen kompakten Dump ohne Objekt-Hashes zu bekommen:

echo Dumper::toText($var, [Dumper::HASH => false]);

Die von toTerminal() verwendeten ANSI-Farben lassen sich über Dumper::$terminalColors anpassen.

Eigenes Rendern von Objekten

Standardmäßig rendert der Dumper ein Objekt, indem er seine Properties auflistet. Manchmal ist das nicht die hilfreichste Ansicht – ein PhpToken zeigt seinen Typ zum Beispiel als numerische ID statt als lesbaren Namen. Sie können dem Dumper beibringen, eine bestimmte Klasse zu rendern, indem Sie in Dumper::$objectExporters einen Exporter registrieren:

use Tracy\Dumper;

Dumper::$objectExporters[PhpToken::class] = function (PhpToken $token, Dumper\Value $value): void {
	$value->value = $token->getTokenName() . ' ' . $token->text;
};

Der Exporter erhält das Objekt und ein Objekt Tracy\Dumper\Value, das beschreibt, wie es angezeigt wird. Eine Zuweisung an $value->value ersetzt die Kopfzeile (standardmäßig den Klassennamen) durch Ihren eigenen Text, sodass Sie statt einer Liste von Properties eine kompakte, lesbare Bezeichnung erhalten. Die Einstellung gilt für jeden Dump dieser Klasse, auch für Objekte, die in Arrays oder anderen Objekten verschachtelt sind. Alternativ können Sie Exporter nur für einen einzigen Aufruf über die Option Dumper::OBJECT_EXPORTERS von Tracy\Dumper::dump() übergeben.