Volcado de variables

Todo el que depura conoce la función var_dump, que imprime información detallada sobre una variable. Por desgracia, su salida carece de formato HTML y se junta en una sola línea, por no hablar de los problemas de escapado de HTML. En la práctica hace falta sustituir var_dump por una función más cómoda. Esa función es dump().

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

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

genera esta salida:

Puede cambiar el tema claro predeterminado por uno oscuro:

Debugger::$dumpTheme = 'dark';

También puede cambiar la profundidad de anidamiento con Debugger::$maxDepth, la longitud de las cadenas mostradas con Debugger::$maxLength y el número de elementos del array o del objeto que se muestran con Debugger::$maxItems. Naturalmente, los valores más bajos aceleran el renderizado.

Debugger::$maxDepth = 2; // predeterminado: 15
Debugger::$maxLength = 50; // predeterminado: 150
Debugger::$maxItems = 50; // predeterminado: 100

La función dump() también puede mostrar el lugar desde el que se llamó y, en el caso de los objetos, la ruta al archivo donde está definida su clase. Eso lo controla la propiedad Debugger::$showLocation:

Debugger::$showLocation = true; // muestra la información de la ubicación
Debugger::$showLocation = false; // la oculta

Para un control más fino, llame directamente a Tracy\Dumper::dump() y pase la opción Dumper::LOCATION con el valor Dumper::LOCATION_CLASS (solo dónde están definidas las clases) o Dumper::LOCATION_SOURCE (también dónde se llamó a dump()).

Alternativas prácticas a dump() son dumpe() (dump & exit) y bdump(). Esta última nos permite volcar los valores de las variables en el panel de la Tracy Bar. Es muy cómodo, porque los volcados quedan separados de la maquetación de la página y además podemos ponerles un título.

bdump([2, 4, 6, 8], 'even numbers up to ten');
bdump([1, 3, 5, 7, 9], 'odd numbers up to ten');

Uso directo de Tracy\Dumper

Detrás de dump() está la clase Tracy\Dumper, que también puede usar directamente. A diferencia de dump(), no depende de Debugger y toma toda su configuración de un array de opciones, lo que la hace práctica para scripts independientes, herramientas de línea de comandos o siempre que necesite el volcado como cadena. Como la configuración viene del array y no de Debugger, los valores predeterminados difieren ligeramente: la profundidad es 7 en lugar de 15, por ejemplo.

Los métodos devuelven el volcado como cadena:

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML para el navegador
$text = Dumper::toText($var);                         // texto plano, p. ej. para un registro
$ansi = Dumper::toTerminal($var);                     // texto con colores ANSI para el terminal

O imprima la variable directamente con Dumper::dump(), que elige automáticamente la salida HTML o de terminal según el entorno:

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

La salida HTML necesita una pequeña hoja de estilos y un script. Cuando vuelque fuera de una aplicación con Tracy activada (es decir, sin Debugger::enable()), imprímalos una vez en la cabecera de la página con Dumper::renderAssets(). Dumper::dump() lo hace por su cuenta, pero toHtml() no.

Opciones

La salida se controla con un array de opciones que se pasa a todos los métodos anteriores:

Opción	Descripción	Predeterminado
`Dumper::DEPTH`	profundidad máxima de anidamiento	`7`
`Dumper::TRUNCATE`	longitud máxima de las cadenas	`150`
`Dumper::ITEMS`	número máximo de elementos mostrados de un array u objeto	`100`
`Dumper::COLLAPSE`	¿colapsar el nodo superior? `true`/`false`, o colapsarlo cuando tenga al menos tantos elementos	`14`
`Dumper::COLLAPSE_COUNT`	colapsar un nodo anidado cuando tenga al menos tantos elementos	`7`
`Dumper::LOCATION`	mostrar la ubicación; `true`/`false`, o `Dumper::LOCATION_CLASS` (solo dónde están definidas las clases) o `Dumper::LOCATION_SOURCE` (también el lugar de la llamada)	desactivado
`Dumper::THEME`	tema de color, `light` o `dark`	`light`
`Dumper::HASH`	¿mostrar los IDs de los objetos (la marca `#`) y las referencias (la marca `&`)?	`true`
`Dumper::DEBUGINFO`	¿usar el método mágico `__debugInfo()` del objeto?	`false`
`Dumper::KEYS_TO_HIDE`	array con los nombres de las claves cuyos valores se ocultan como `*****`	`[]`
`Dumper::SCRUBBER`	callback `fn(string $key, mixed $value, ?string $class): bool` que devuelve `true` para los valores sensibles	ninguno
`Dumper::OBJECT_EXPORTERS`	renderizado propio de los objetos, véase abajo	`[]`

Las opciones COLLAPSE, COLLAPSE_COUNT y THEME solo se aplican a la salida HTML interactiva.

La opción SCRUBBER oculta del volcado los valores sensibles; véase Scrubber propio para un ejemplo completo.

Por ejemplo, para obtener un volcado compacto sin los hashes de los objetos:

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

Los colores ANSI que usa toTerminal() se pueden personalizar con Dumper::$terminalColors.

Renderizado propio de los objetos

De forma predeterminada, el dumper renderiza un objeto enumerando sus propiedades. A veces esa no es la vista más útil: un PhpToken, por ejemplo, muestra su tipo como un ID numérico en lugar de como un nombre legible. Puede enseñarle al dumper cómo renderizar una clase concreta registrando un exportador en Dumper::$objectExporters:

use Tracy\Dumper;

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

El exportador recibe el objeto y un objeto Tracy\Dumper\Value que describe cómo se mostrará. Asignar a $value->value sustituye la cabecera (por defecto, el nombre de la clase) por su propio texto, así que en lugar de una lista de propiedades obtiene una etiqueta compacta y legible. El ajuste se aplica a todos los volcados de esa clase, incluso a los objetos anidados dentro de arrays u otros objetos. Alternativamente puede pasar exportadores solo para una llamada concreta con la opción Dumper::OBJECT_EXPORTERS de Tracy\Dumper::dump().