Dumpování
*********

Každý ladič je dobrým kamarádem s funkcí [php:var_dump], která podrobně vypíše obsah proměnné. Bohužel v prostředí HTML výpis pozbude formátování a slije se do jednoho řádku, o sanitizaci HTML kódu ani nemluvě. V praxi je nezbytné `var_dump` nahradit šikovnější funkcí. Tou je právě `dump()`.

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

dump($arr);
// nebo Debugger::dump($arr);
```

vygeneruje výstup:

[* dump-basic.webp *]

Vychozí světlý motiv můžete změnit na tmavý:

```php
Debugger::$dumpTheme = 'dark';
```

[* dump-dark.webp *]

Dále můžeme změnit hloubku zanoření pomocí [Debugger::$maxDepth |api:Tracy\Debugger::$maxDepth], délku zobrazovaných řetězců pomocí [Debugger::$maxLength |api:Tracy\Debugger::$maxLength] a počet zobrazených položek pole či objektu pomocí [Debugger::$maxItems |api:Tracy\Debugger::$maxItems]. Nižší hodnoty laděnku přirozeně zrychlí.

```php
Debugger::$maxDepth = 2; // default: 15
Debugger::$maxLength = 50; // default: 150
Debugger::$maxItems = 50; // default: 100
```

Funkce `dump()` umí vypsat i místo, kde byla zavolána, a u objektů cestu k souboru, ve kterém je definována jejich třída. Řídí se to vlastností [Debugger::$showLocation |api:Tracy\Debugger::$showLocation]:

```php
Debugger::$showLocation = true; // zobrazí informace o umístění
Debugger::$showLocation = false; // skryje je
```

Pro jemnější řízení volejte přímo `Tracy\Dumper::dump()` a předejte option `Dumper::LOCATION` s hodnotou `Dumper::LOCATION_CLASS` (jen kde jsou definovány třídy) nebo `Dumper::LOCATION_SOURCE` (navíc kde byla `dump()` zavolána).

Praktickou alternativou k `dump()` je `dumpe()` (dump & exit) a `bdump()`. Ten nám umožňuje vypsat hodnotu proměnné v panelu Tracy Baru. To je velmi šikovné, jelikož jsou dumpy oddělené od rozložení stránky a také k nim můžeme umístit komentář.

```php
bdump([2, 4, 6, 8], 'sudá čísla do deseti');
bdump([1, 3, 5, 7, 9], 'lichá čísla do deseti');
```

[* bardump-cs.webp *]


Přímé použití Tracy\Dumper
==========================

Za funkcí `dump()` stojí třída `Tracy\Dumper`, kterou můžete používat i přímo. Na rozdíl od `dump()` nezávisí na `Debugger`u a veškeré nastavení přebírá z pole voleb, což se hodí pro samostatné skripty, CLI nástroje nebo kdykoli potřebujete dump jako řetězec. Protože nastavení pochází z pole a ne z `Debugger`u, výchozí hodnoty se mírně liší: hloubka je například `7` místo `15`.

Metody vrací dump jako řetězec:

```php
use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML pro prohlížeč
$text = Dumper::toText($var);                         // prostý text, např. do logu
$ansi = Dumper::toTerminal($var);                     // text s ANSI barvami pro terminál
```

Nebo proměnnou rovnou vypište pomocí `Dumper::dump()`, která podle prostředí automaticky zvolí HTML nebo terminálový výstup:

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

.[note]
HTML výstup potřebuje drobný styl a skript. Když dumpujete mimo aplikaci se zapnutou Tracy (tj. bez `Debugger::enable()`), vypište je jednou v hlavičce stránky pomocí `Dumper::renderAssets()`. `Dumper::dump()` to udělá sama, `toHtml()` nikoli.


Volby
-----

Výstup řídí pole voleb předané všem výše uvedeným metodám:

| Volba | Popis | Výchozí
|--------|-------------|--------
| `Dumper::DEPTH` | maximální hloubka zanoření | `7`
| `Dumper::TRUNCATE` | maximální délka řetězců | `150`
| `Dumper::ITEMS` | maximální počet zobrazených položek pole/objektu | `100`
| `Dumper::COLLAPSE` | sbalit kořenový uzel? `true`/`false`, nebo sbalit, jakmile má aspoň tolik položek | `14`
| `Dumper::COLLAPSE_COUNT` | sbalit zanořený uzel, jakmile má aspoň tolik položek | `7`
| `Dumper::LOCATION` | zobrazit místo; `true`/`false`, nebo `Dumper::LOCATION_CLASS` (jen kde jsou definovány třídy) či `Dumper::LOCATION_SOURCE` (navíc místo volání) | vypnuto
| `Dumper::THEME` | barevné téma, `light` nebo `dark` | `light`
| `Dumper::HASH` | zobrazit ID objektů (značka `#`) a reference (značka `&`)? | `true`
| `Dumper::DEBUGINFO` | použít magickou metodu objektu `__debugInfo()`? | `false`
| `Dumper::KEYS_TO_HIDE` | pole názvů klíčů, jejichž hodnoty se skryjí jako `*****` | `[]`
| `Dumper::SCRUBBER` | callback `fn(string $key, mixed $value, ?string $class): bool` vracející `true` pro citlivé hodnoty | žádný
| `Dumper::OBJECT_EXPORTERS` | vlastní vykreslení objektů, viz níže | `[]`

Volby `COLLAPSE`, `COLLAPSE_COUNT` a `THEME` se týkají jen interaktivního HTML výstupu.

Volba `SCRUBBER` skryje z výpisu citlivé hodnoty; kompletní příklad viz [Vlastní scrubber |recipes#vlastni-scrubber].

Například kompaktní výpis bez hashů objektů získáte takto:

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

ANSI barvy použité metodou `toTerminal()` lze upravit přes `Dumper::$terminalColors`.


Vlastní vykreslení objektů
==========================

Ve výchozím stavu dumper vykreslí objekt výpisem jeho properties. Někdy to ale není nejužitečnější pohled - třeba `PhpToken` zobrazí svůj typ jako číselné ID místo čitelného názvu. Dumperu můžete říct, jak má konkrétní třídu vykreslit, zaregistrováním exportéru do `Dumper::$objectExporters`:

```php
use Tracy\Dumper;

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

Exportér dostane objekt a objekt `Tracy\Dumper\Value` popisující, jak se objekt zobrazí. Přiřazení do `$value->value` nahradí hlavičku (ve výchozím stavu název třídy) vaším vlastním textem, takže místo výpisu properties dostanete kompaktní, čitelný popisek. Nastavení se uplatní na každý dump dané třídy, i na objekty zanořené v polích či jiných objektech. Případně můžete exportéry předat jen pro jedno volání pomocí option `Dumper::OBJECT_EXPORTERS` funkce `Tracy\Dumper::dump()`.