Variablen ausgeben
******************
Jedem, der debuggt, ist die Funktion [php: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()`.
```php
$arr = [10, 20.2, true, null, 'hello'];
dump($arr);
// oder Debugger::dump($arr);
```
erzeugt die Ausgabe:
[* dump-basic.webp *]
Das standardmäßige helle Theme können Sie auf dunkel umstellen:
```php
Debugger::$dumpTheme = 'dark';
```
[* dump-dark.webp *]
Sie können außerdem die Verschachtelungstiefe über [Debugger::$maxDepth |api:Tracy\Debugger::$maxDepth], die Länge der angezeigten Strings über [Debugger::$maxLength |api:Tracy\Debugger::$maxLength] und die Anzahl der angezeigten Array- oder Objektelemente über [Debugger::$maxItems |api:Tracy\Debugger::$maxItems] ändern. Niedrigere Werte beschleunigen das Rendern natürlich.
```php
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 |api:Tracy\Debugger::$showLocation]:
```php
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.
```php
bdump([2, 4, 6, 8], 'gerade Zahlen bis zehn');
bdump([1, 3, 5, 7, 9], 'ungerade Zahlen bis zehn');
```
[* bardump-en.webp *]
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:
```php
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:
```php
Dumper::dump($var, [Dumper::DEPTH => 3]);
```
.[note]
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 |recipes#Eigener Scrubber].
Um zum Beispiel einen kompakten Dump ohne Objekt-Hashes zu bekommen:
```php
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:
```php
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.
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().
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.
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:
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.