Dump delle variabili

Ogni debugger conosce la funzione var_dump, che stampa informazioni dettagliate su una variabile. Purtroppo il suo output non ha formattazione HTML e si fonde in un'unica riga, per non parlare dei problemi con l'escaping HTML. Nella pratica è quindi necessario sostituire var_dump con una funzione più comoda. E quella funzione è dump().

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

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

produce questo output:

Il tema chiaro predefinito lo potete cambiare in scuro:

Debugger::$dumpTheme = 'dark';

Potete anche cambiare la profondità di annidamento con Debugger::$maxDepth, la lunghezza delle stringhe mostrate con Debugger::$maxLength e il numero di elementi di array o oggetti mostrati con Debugger::$maxItems. Naturalmente valori più bassi accelerano il rendering.

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

La funzione dump() sa mostrare anche il punto da cui è stata chiamata e, per gli oggetti, il percorso del file in cui è definita la loro classe. Lo governa la proprietà Debugger::$showLocation:

Debugger::$showLocation = true; // mostra l'informazione sul punto
Debugger::$showLocation = false; // la nasconde

Per un controllo più fine chiamate direttamente Tracy\Dumper::dump() e passate l'opzione Dumper::LOCATION impostata a Dumper::LOCATION_CLASS (solo dove sono definite le classi) oppure Dumper::LOCATION_SOURCE (anche dove è stato chiamato dump()).

Alternative pratiche a dump() sono dumpe() (dump & exit) e bdump(). Quest'ultima ci permette di fare il dump dei valori delle variabili nel pannello della Tracy Bar. Il che è molto comodo, perché i dump restano separati dal layout della pagina e possiamo per di più dare loro un titolo.

bdump([2, 4, 6, 8], 'numeri pari fino a dieci');
bdump([1, 3, 5, 7, 9], 'numeri dispari fino a dieci');

Usare direttamente Tracy\Dumper

Dietro dump() sta la classe Tracy\Dumper, che potete usare anche direttamente. A differenza di dump() non dipende da Debugger e prende tutte le sue impostazioni da un array di opzioni, il che la rende comoda per script autonomi, strumenti CLI o ogni volta che vi serve il dump come stringa. Poiché le impostazioni vengono dall'array e non da Debugger, i valori predefiniti differiscono leggermente: la profondità è per esempio 7 invece di 15.

I metodi restituiscono il dump come stringa:

use Tracy\Dumper;

$html = Dumper::toHtml($var, [Dumper::DEPTH => 3]);  // HTML per il browser
$text = Dumper::toText($var);                         // testo semplice, per esempio per un log
$ansi = Dumper::toTerminal($var);                     // testo con colori ANSI per il terminale

Oppure stampate la variabile subito con Dumper::dump(), che sceglie automaticamente l'output HTML o da terminale secondo l'ambiente:

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

L'output HTML ha bisogno di un piccolo foglio di stile e di uno script. Quando fate il dump fuori da un'applicazione con Tracy attiva (cioè senza Debugger::enable()), stampateli una volta nell'head della pagina con Dumper::renderAssets(). Dumper::dump() lo fa da sé, toHtml() no.

Opzioni

L'output è governato dall'array di opzioni passato a tutti i metodi sopra:

Le opzioni COLLAPSE, COLLAPSE_COUNT e THEME valgono solo per l'output HTML interattivo.

L'opzione SCRUBBER nasconde dal dump i valori sensibili; un esempio completo lo trovate in Scrubber personalizzato.

Per ottenere per esempio un dump compatto senza gli hash degli oggetti:

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

I colori ANSI usati da toTerminal() si possono personalizzare con Dumper::$terminalColors.

Rendering personalizzato degli oggetti

Per impostazione predefinita il dumper renderizza un oggetto elencandone le proprietà. A volte però non è la vista più utile: un PhpToken, per esempio, mostra il proprio tipo come ID numerico invece che come nome leggibile. Potete insegnare al dumper come renderizzare una determinata classe registrando un exporter in Dumper::$objectExporters:

use Tracy\Dumper;

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

L'exporter riceve l'oggetto e un oggetto Tracy\Dumper\Value che descrive come verrà mostrato. Assegnare a $value->value sostituisce l'intestazione (per impostazione predefinita il nome della classe) con un vostro testo, così invece di un elenco di proprietà ottenete un'etichetta compatta e leggibile. L'impostazione vale per ogni dump di quella classe, anche per gli oggetti annidati dentro array o altri oggetti. In alternativa potete passare gli exporter per una sola chiamata con l'opzione Dumper::OBJECT_EXPORTERS di Tracy\Dumper::dump().