Nette Documentation Preview

syntax 
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().

$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.