Nette Documentation Preview

syntax 
Dump delle variabili
********************

Ogni debugger conosce la funzione [php: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()`.

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

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

produce questo output:

[* dump-basic.webp *]

Il tema chiaro predefinito lo potete cambiare in scuro:

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

[* dump-dark.webp *]

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

```php
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 |api:Tracy\Debugger::$showLocation]:

```php
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.

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

[* bardump-en.webp *]


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:

```php
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:

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

.[note]
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:

| Opzione | Descrizione | Predefinito
|--------|-------------|--------
| `Dumper::DEPTH` | profondità massima di annidamento | `7`
| `Dumper::TRUNCATE` | lunghezza massima delle stringhe | `150`
| `Dumper::ITEMS` | numero massimo di elementi mostrati in un array/oggetto | `100`
| `Dumper::COLLAPSE` | comprimere il nodo principale? `true`/`false`, oppure comprimerlo quando ha almeno questo numero di elementi | `14`
| `Dumper::COLLAPSE_COUNT` | comprimere un nodo annidato quando ha almeno questo numero di elementi | `7`
| `Dumper::LOCATION` | mostrare il punto; `true`/`false`, oppure `Dumper::LOCATION_CLASS` (solo dove sono definite le classi) o `Dumper::LOCATION_SOURCE` (anche il punto della chiamata) | disattivo
| `Dumper::THEME` | tema di colori, `light` oppure `dark` | `light`
| `Dumper::HASH` | mostrare gli ID degli oggetti (il marcatore `#`) e i riferimenti (il marcatore `&`)? | `true`
| `Dumper::DEBUGINFO` | usare il metodo magico `__debugInfo()` dell'oggetto? | `false`
| `Dumper::KEYS_TO_HIDE` | array di nomi di chiavi i cui valori vengono nascosti come `*****` | `[]`
| `Dumper::SCRUBBER` | callback `fn(string $key, mixed $value, ?string $class): bool` che restituisce `true` per i valori sensibili | nessuno
| `Dumper::OBJECT_EXPORTERS` | rendering personalizzato degli oggetti, vedi sotto | `[]`

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 |recipes#Scrubber personalizzato].

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

```php
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`:

```php
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()`.

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:

Opzione Descrizione Predefinito
Dumper::DEPTH profondità massima di annidamento 7
Dumper::TRUNCATE lunghezza massima delle stringhe 150
Dumper::ITEMS numero massimo di elementi mostrati in un array/oggetto 100
Dumper::COLLAPSE comprimere il nodo principale? true/false, oppure comprimerlo quando ha almeno questo numero di elementi 14
Dumper::COLLAPSE_COUNT comprimere un nodo annidato quando ha almeno questo numero di elementi 7
Dumper::LOCATION mostrare il punto; true/false, oppure Dumper::LOCATION_CLASS (solo dove sono definite le classi) o Dumper::LOCATION_SOURCE (anche il punto della chiamata) disattivo
Dumper::THEME tema di colori, light oppure dark light
Dumper::HASH mostrare gli ID degli oggetti (il marcatore #) e i riferimenti (il marcatore &)? true
Dumper::DEBUGINFO usare il metodo magico __debugInfo() dell'oggetto? false
Dumper::KEYS_TO_HIDE array di nomi di chiavi i cui valori vengono nascosti come ***** []
Dumper::SCRUBBER callback fn(string $key, mixed $value, ?string $class): bool che restituisce true per i valori sensibili nessuno
Dumper::OBJECT_EXPORTERS rendering personalizzato degli oggetti, vedi sotto []

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().