Nette Documentation Preview

syntax 
Вывод переменных
****************

Каждому отладчику знакома функция [php:var_dump], которая выводит подробную информацию о переменной. К сожалению, её вывод лишён HTML-форматирования и сливается в одну строку, не говоря уже об экранировании HTML. На практике `var_dump` необходимо заменить более удобной функцией. Такая функция - `dump()`.

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

dump($arr);
// или Debugger::dump($arr);
```

порождает вывод:

[* dump-basic.webp *]

Светлую тему по умолчанию можно сменить на тёмную:

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

[* dump-dark.webp *]

Можно также изменить глубину вложенности через [Debugger::$maxDepth |api:Tracy\Debugger::$maxDepth], длину выводимых строк через [Debugger::$maxLength |api:Tracy\Debugger::$maxLength] и количество показываемых элементов массива или объекта через [Debugger::$maxItems |api:Tracy\Debugger::$maxItems]. Естественно, меньшие значения ускоряют отрисовку.

```php
Debugger::$maxDepth = 2; // по умолчанию: 15
Debugger::$maxLength = 50; // по умолчанию: 150
Debugger::$maxItems = 50; // по умолчанию: 100
```

Функция `dump()` может показывать и место, откуда она была вызвана, а для объектов - путь к файлу, где определён их класс. Этим управляет свойство [Debugger::$showLocation |api:Tracy\Debugger::$showLocation]:

```php
Debugger::$showLocation = true; // показывает сведения о месте
Debugger::$showLocation = false; // скрывает их
```

Для более тонкого управления вызовите напрямую `Tracy\Dumper::dump()` и передайте параметр `Dumper::LOCATION` со значением `Dumper::LOCATION_CLASS` (только места определения классов) или `Dumper::LOCATION_SOURCE` (ещё и место вызова `dump()`).

Практичные альтернативы `dump()` - это `dumpe()` (dump & exit) и `bdump()`. Последняя позволяет выводить значения переменных в панели Tracy Bar. Это очень удобно, потому что дампы отделены от оформления страницы и им можно ещё и дать заголовок.

```php
bdump([2, 4, 6, 8], 'чётные числа до десяти');
bdump([1, 3, 5, 7, 9], 'нечётные числа до десяти');
```

[* bardump-en.webp *]


Прямое использование Tracy\Dumper
=================================

За `dump()` стоит класс `Tracy\Dumper`, который вы можете использовать и напрямую. В отличие от `dump()`, он не зависит от `Debugger` и берёт все настройки из массива параметров, что удобно для самостоятельных скриптов, CLI-инструментов или всегда, когда дамп нужен в виде строки. Поскольку настройки берутся из массива, а не из `Debugger`, значения по умолчанию немного отличаются: глубина, например, равна `7` вместо `15`.

Методы возвращают дамп в виде строки:

```php
use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML для браузера
$text = Dumper::toText($var);                         // обычный текст, например для лога
$ansi = Dumper::toTerminal($var);                     // текст с ANSI-цветами для терминала
```

Либо выведите переменную сразу через `Dumper::dump()`, который сам выбирает HTML или терминальный вывод в зависимости от окружения:

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

.[note]
HTML-выводу нужны небольшой стиль и скрипт. Когда вы выводите дамп вне приложения с включённой Tracy (то есть без `Debugger::enable()`), выведите их один раз в head страницы через `Dumper::renderAssets()`. `Dumper::dump()` делает это сам, а `toHtml()` - нет.


Параметры
---------

Выводом управляет массив параметров, передаваемый всем перечисленным выше методам:

| Параметр | Описание | По умолчанию
|--------|-------------|--------
| `Dumper::DEPTH` | максимальная глубина вложенности | `7`
| `Dumper::TRUNCATE` | максимальная длина строк | `150`
| `Dumper::ITEMS` | максимальное количество показываемых элементов массива или объекта | `100`
| `Dumper::COLLAPSE` | свернуть верхний узел? `true`/`false` либо свернуть, когда у него хотя бы столько элементов | `14`
| `Dumper::COLLAPSE_COUNT` | свернуть вложенный узел, когда у него хотя бы столько элементов | `7`
| `Dumper::LOCATION` | показывать место; `true`/`false` либо `Dumper::LOCATION_CLASS` (только места определения классов) или `Dumper::LOCATION_SOURCE` (ещё и место вызова) | выключено
| `Dumper::THEME` | цветовая тема, `light` или `dark` | `light`
| `Dumper::HASH` | показывать ID объектов (метка `#`) и ссылки (метка `&`)? | `true`
| `Dumper::DEBUGINFO` | использовать магический метод объекта `__debugInfo()`? | `false`
| `Dumper::KEYS_TO_HIDE` | массив имён ключей, значения которых скрываются как `*****` | `[]`
| `Dumper::SCRUBBER` | callback `fn(string $key, mixed $value, ?string $class): bool`, возвращающий `true` для конфиденциальных значений | нет
| `Dumper::OBJECT_EXPORTERS` | собственная отрисовка объектов, см. ниже | `[]`

Параметры `COLLAPSE`, `COLLAPSE_COUNT` и `THEME` относятся только к интерактивному HTML-выводу.

Параметр `SCRUBBER` скрывает в дампе конфиденциальные значения, полный пример смотрите в разделе [Собственный scrubber |recipes#Собственный scrubber].

Например, чтобы получить компактный дамп без хешей объектов:

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

ANSI-цвета, используемые в `toTerminal()`, можно настроить через `Dumper::$terminalColors`.


Собственная отрисовка объектов
==============================

По умолчанию dumper отображает объект перечислением его свойств. Иногда это не самый полезный вид: например, `PhpToken` показывает свой тип числовым идентификатором вместо читаемого имени. Вы можете научить dumper отрисовывать конкретный класс, зарегистрировав экспортёр в `Dumper::$objectExporters`:

```php
use Tracy\Dumper;

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

Экспортёр получает объект и объект `Tracy\Dumper\Value`, описывающий, как объект будет показан. Присваивание в `$value->value` заменяет заголовок (по умолчанию имя класса) вашим собственным текстом, так что вместо списка свойств вы получите компактную читаемую подпись. Настройка действует для каждого дампа этого класса, в том числе для объектов, вложенных в массивы или другие объекты. Как вариант, экспортёры можно передать только для одного вызова через параметр `Dumper::OBJECT_EXPORTERS` метода `Tracy\Dumper::dump()`.

Вывод переменных

Каждому отладчику знакома функция var_dump, которая выводит подробную информацию о переменной. К сожалению, её вывод лишён HTML-форматирования и сливается в одну строку, не говоря уже об экранировании HTML. На практике var_dump необходимо заменить более удобной функцией. Такая функция – dump().

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

dump($arr);
// или Debugger::dump($arr);

порождает вывод:

Светлую тему по умолчанию можно сменить на тёмную:

Debugger::$dumpTheme = 'dark';

Можно также изменить глубину вложенности через Debugger::$maxDepth, длину выводимых строк через Debugger::$maxLength и количество показываемых элементов массива или объекта через Debugger::$maxItems. Естественно, меньшие значения ускоряют отрисовку.

Debugger::$maxDepth = 2; // по умолчанию: 15
Debugger::$maxLength = 50; // по умолчанию: 150
Debugger::$maxItems = 50; // по умолчанию: 100

Функция dump() может показывать и место, откуда она была вызвана, а для объектов – путь к файлу, где определён их класс. Этим управляет свойство Debugger::$showLocation:

Debugger::$showLocation = true; // показывает сведения о месте
Debugger::$showLocation = false; // скрывает их

Для более тонкого управления вызовите напрямую Tracy\Dumper::dump() и передайте параметр Dumper::LOCATION со значением Dumper::LOCATION_CLASS (только места определения классов) или Dumper::LOCATION_SOURCE (ещё и место вызова dump()).

Практичные альтернативы dump() – это dumpe() (dump & exit) и bdump(). Последняя позволяет выводить значения переменных в панели Tracy Bar. Это очень удобно, потому что дампы отделены от оформления страницы и им можно ещё и дать заголовок.

bdump([2, 4, 6, 8], 'чётные числа до десяти');
bdump([1, 3, 5, 7, 9], 'нечётные числа до десяти');

Прямое использование Tracy\Dumper

За dump() стоит класс Tracy\Dumper, который вы можете использовать и напрямую. В отличие от dump(), он не зависит от Debugger и берёт все настройки из массива параметров, что удобно для самостоятельных скриптов, CLI-инструментов или всегда, когда дамп нужен в виде строки. Поскольку настройки берутся из массива, а не из Debugger, значения по умолчанию немного отличаются: глубина, например, равна 7 вместо 15.

Методы возвращают дамп в виде строки:

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML для браузера
$text = Dumper::toText($var);                         // обычный текст, например для лога
$ansi = Dumper::toTerminal($var);                     // текст с ANSI-цветами для терминала

Либо выведите переменную сразу через Dumper::dump(), который сам выбирает HTML или терминальный вывод в зависимости от окружения:

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

HTML-выводу нужны небольшой стиль и скрипт. Когда вы выводите дамп вне приложения с включённой Tracy (то есть без Debugger::enable()), выведите их один раз в head страницы через Dumper::renderAssets(). Dumper::dump() делает это сам, а toHtml() – нет.

Параметры

Выводом управляет массив параметров, передаваемый всем перечисленным выше методам:

Параметр Описание По умолчанию
Dumper::DEPTH максимальная глубина вложенности 7
Dumper::TRUNCATE максимальная длина строк 150
Dumper::ITEMS максимальное количество показываемых элементов массива или объекта 100
Dumper::COLLAPSE свернуть верхний узел? true/false либо свернуть, когда у него хотя бы столько элементов 14
Dumper::COLLAPSE_COUNT свернуть вложенный узел, когда у него хотя бы столько элементов 7
Dumper::LOCATION показывать место; true/false либо Dumper::LOCATION_CLASS (только места определения классов) или Dumper::LOCATION_SOURCE (ещё и место вызова) выключено
Dumper::THEME цветовая тема, light или dark light
Dumper::HASH показывать ID объектов (метка #) и ссылки (метка &)? true
Dumper::DEBUGINFO использовать магический метод объекта __debugInfo()? false
Dumper::KEYS_TO_HIDE массив имён ключей, значения которых скрываются как ***** []
Dumper::SCRUBBER callback fn(string $key, mixed $value, ?string $class): bool, возвращающий true для конфиденциальных значений нет
Dumper::OBJECT_EXPORTERS собственная отрисовка объектов, см. ниже []

Параметры COLLAPSE, COLLAPSE_COUNT и THEME относятся только к интерактивному HTML-выводу.

Параметр SCRUBBER скрывает в дампе конфиденциальные значения, полный пример смотрите в разделе Собственный scrubber.

Например, чтобы получить компактный дамп без хешей объектов:

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

ANSI-цвета, используемые в toTerminal(), можно настроить через Dumper::$terminalColors.

Собственная отрисовка объектов

По умолчанию dumper отображает объект перечислением его свойств. Иногда это не самый полезный вид: например, PhpToken показывает свой тип числовым идентификатором вместо читаемого имени. Вы можете научить dumper отрисовывать конкретный класс, зарегистрировав экспортёр в Dumper::$objectExporters:

use Tracy\Dumper;

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

Экспортёр получает объект и объект Tracy\Dumper\Value, описывающий, как объект будет показан. Присваивание в $value->value заменяет заголовок (по умолчанию имя класса) вашим собственным текстом, так что вместо списка свойств вы получите компактную читаемую подпись. Настройка действует для каждого дампа этого класса, в том числе для объектов, вложенных в массивы или другие объекты. Как вариант, экспортёры можно передать только для одного вызова через параметр Dumper::OBJECT_EXPORTERS метода Tracy\Dumper::dump().