Nette Documentation Preview

syntax 
Dumpowanie zmiennych
********************

Każdy debugujący zna funkcję [php: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()`.

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

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

generuje wyjście:

[* dump-basic.webp *]

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

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

[* dump-dark.webp *]

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

```php
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 |api:Tracy\Debugger::$showLocation]:

```php
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ł.

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

[* bardump-en.webp *]


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:

```php
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:

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

.[note]
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 |recipes#Własny scrubber].

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

```php
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`:

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

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