Вывод переменных
****************
Каждому отладчику знакома функция [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().
Светлую тему по умолчанию можно сменить на тёмную:
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
массив имён ключей, значения которых скрываются как *****
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().