Dumpowanie zmiennych

Każdy debugujący zna funkcję var_dump, która wypisuje szczegółowe informacje o zmiennej. Niestety jej wyjście nie ma formatowania HTML i zlewa się w jedną linię, nie mówiąc o problemach z escapowaniem HTML. W praktyce trzeba zastąpić var_dump wygodniejszą funkcją. Tą funkcją jest dump().

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

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

generuje wyjście:

Domyślny jasny motyw możesz zmienić na ciemny:

Debugger::$dumpTheme = 'dark';

Możesz też zmienić głębokość zagnieżdżenia za pomocą Debugger::$maxDepth, długość wyświetlanych ciągów za pomocą Debugger::$maxLength i liczbę wyświetlanych pozycji tablicy albo obiektu za pomocą Debugger::$maxItems. Naturalnie niższe wartości przyspieszają renderowanie.

Debugger::$maxDepth = 2; // domyślnie: 15
Debugger::$maxLength = 50; // domyślnie: 150
Debugger::$maxItems = 50; // domyślnie: 100

Funkcja dump() potrafi też wyświetlić miejsce, z którego została wywołana, a dla obiektów ścieżkę do pliku, w którym zdefiniowana jest ich klasa. Steruje tym właściwość Debugger::$showLocation:

Debugger::$showLocation = true; // wyświetla informację o miejscu
Debugger::$showLocation = false; // ukrywa ją

Dla precyzyjniejszej kontroli wywołaj bezpośrednio Tracy\Dumper::dump() i przekaż opcję Dumper::LOCATION ustawioną na Dumper::LOCATION_CLASS (tylko miejsca definicji klas) albo Dumper::LOCATION_SOURCE (także miejsce wywołania dump()).

Praktycznymi alternatywami dla dump() są dumpe() (dump & exit) i bdump(). Ta ostatnia pozwala nam dumpować wartości zmiennych w panelu Tracy Bara. Jest to bardzo wygodne, bo dumpy są oddzielone od layoutu strony, a poza tym możemy dodać im tytuł.

bdump([2, 4, 6, 8], 'liczby parzyste do dziesięciu');
bdump([1, 3, 5, 7, 9], 'liczby nieparzyste do dziesięciu');

Bezpośrednie użycie Tracy\Dumper

Za dump() stoi klasa Tracy\Dumper, której możesz też użyć bezpośrednio. W przeciwieństwie do dump() nie opiera się na Debuggerze i wszystkie ustawienia bierze z tablicy opcji, co czyni ją przydatną w samodzielnych skryptach, narzędziach CLI albo zawsze wtedy, gdy potrzebujesz dumpa jako ciągu. Ponieważ ustawienia pochodzą z tablicy, a nie z Debuggera, wartości domyślne nieco się różnią: głębokość to na przykład 7 zamiast 15.

Metody zwracają dump jako ciąg:

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML dla przeglądarki
$text = Dumper::toText($var);                         // zwykły tekst, np. do logu
$ansi = Dumper::toTerminal($var);                     // tekst z kolorami ANSI dla terminala

Albo wypisz zmienną od razu za pomocą Dumper::dump(), które automatycznie wybiera wyjście HTML albo terminalowe zgodnie ze środowiskiem:

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

Wyjście HTML potrzebuje małego arkusza stylów i skryptu. Gdy dumpujesz poza aplikacją z włączoną Tracy (czyli bez Debugger::enable()), wypisz je raz w nagłówku strony za pomocą Dumper::renderAssets(). Dumper::dump() robi to samo, ale toHtml() już nie.

Opcje

Wyjściem steruje tablica opcji przekazywana wszystkim powyższym metodom:

Opcja	Opis	Domyślnie
`Dumper::DEPTH`	maksymalna głębokość zagnieżdżenia	`7`
`Dumper::TRUNCATE`	maksymalna długość ciągów	`150`
`Dumper::ITEMS`	maksymalna liczba wyświetlanych pozycji tablicy/obiektu	`100`
`Dumper::COLLAPSE`	zwinąć węzeł najwyższego poziomu? `true`/`false` albo zwinąć go, gdy ma co najmniej tyle pozycji	`14`
`Dumper::COLLAPSE_COUNT`	zwinąć węzeł zagnieżdżony, gdy ma co najmniej tyle pozycji	`7`
`Dumper::LOCATION`	pokazać miejsce; `true`/`false` albo `Dumper::LOCATION_CLASS` (tylko miejsca definicji klas) czy `Dumper::LOCATION_SOURCE` (także miejsce wywołania)	wyłączone
`Dumper::THEME`	motyw kolorystyczny, `light` albo `dark`	`light`
`Dumper::HASH`	pokazać ID obiektów (znacznik `#`) i referencje (znacznik `&`)?	`true`
`Dumper::DEBUGINFO`	użyć magicznej metody obiektu `__debugInfo()`?	`false`
`Dumper::KEYS_TO_HIDE`	tablica nazw kluczy, których wartości są ukrywane jako `*****`	`[]`
`Dumper::SCRUBBER`	callback `fn(string $key, mixed $value, ?string $class): bool` zwracający `true` dla wartości wrażliwych	brak
`Dumper::OBJECT_EXPORTERS`	własne renderowanie obiektów, patrz niżej	`[]`

Opcje COLLAPSE, COLLAPSE_COUNT i THEME dotyczą tylko interaktywnego wyjścia HTML.

Opcja SCRUBBER ukrywa w dumpie wartości wrażliwe; kompletny przykład znajdziesz w Własny scrubber.

Na przykład żeby uzyskać zwięzły dump bez hashy obiektów:

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

Kolory ANSI używane przez toTerminal() można dostosować przez Dumper::$terminalColors.

Własne renderowanie obiektów

Domyślnie dumper renderuje obiekt, wypisując jego właściwości. Czasem nie jest to najbardziej pomocny widok: PhpToken na przykład pokazuje swój typ jako numeryczne ID zamiast czytelnej nazwy. Możesz nauczyć dumper, jak renderować konkretną klasę, rejestrując eksporter w Dumper::$objectExporters:

use Tracy\Dumper;

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

Eksporter otrzymuje obiekt i obiekt Tracy\Dumper\Value opisujący, jak zostanie wyświetlony. Przypisanie do $value->value zastępuje nagłówek (domyślnie nazwę klasy) Twoim własnym tekstem, więc zamiast listy właściwości dostajesz zwięzłą, czytelną etykietę. Ustawienie dotyczy każdego dumpa tej klasy, także obiektów zagnieżdżonych w tablicach albo innych obiektach. Alternatywnie możesz przekazać eksportery tylko dla jednego wywołania przez opcję Dumper::OBJECT_EXPORTERS metody Tracy\Dumper::dump().