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

Каждому отладчику знакома функция 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().