Dumpování

Každý ladič je dobrým kamarádem s funkcí 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().

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

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

vygeneruje výstup:

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

Debugger::$dumpTheme = 'dark';

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

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:

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ář.

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

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 Debuggeru 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 Debuggeru, výchozí hodnoty se mírně liší: hloubka je například 7 místo 15.

Metody vrací dump jako řetězec:

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:

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

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.

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

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:

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