Nette Documentation Preview

syntax 
Ricette
*******


Content Security Policy
=======================

Se il vostro sito usa la Content Security Policy (CSP), dovrete aggiungere alla direttiva `script-src` i valori `'nonce-<valore>'` e `'strict-dynamic'` perché Tracy funzioni correttamente. Alcuni plugin di terze parti possono richiedere altre direttive. Il nonce non è supportato nella direttiva `style-src`; se usate questa direttiva, dovete aggiungere `'unsafe-inline'`, cosa che però andrebbe evitata in modalità produzione.

Esempio di configurazione per il [Nette Framework |nette:configuring]:

```neon
http:
	csp:
		script-src: [nonce, strict-dynamic]
```

Esempio in PHP puro:

```php
$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");
```


Caricamento più veloce
======================

L'integrazione di base è semplice. Se però nella vostra pagina web ci sono script bloccanti che si caricano lentamente, possono rallentare il caricamento di Tracy. La soluzione è mettere nel template `<?php Tracy\Debugger::renderLoader() ?>` prima di qualsiasi script:

```latte
<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
</head>
```


Individuare la sorgente dell'output
===================================

Vi siete mai imbattuti in *Cannot modify header information - headers already sent*? Compare quando qualcosa (uno spazio sperduto, una riga vuota o un BOM all'inizio di un file) viene inviato al browser prima che il vostro codice imposti un header HTTP o avvii una sessione. Trovare il colpevole è noioso.

Vi aiuta `Tracy\OutputDebugger`. Attivatelo come primissima cosa nel programma:

```php
Tracy\OutputDebugger::enable();
```

Sorveglia tutto l'output e alla fine della pagina stampa l'elenco di ogni punto da cui è stato inviato dell'output, con il file, la riga e un link che lo apre nel vostro editor. Viene evidenziato anche un byte order mark (BOM) all'inizio del file, perché è una causa invisibile molto frequente del problema.


Debug delle richieste AJAX
==========================

Tracy cattura automaticamente le richieste AJAX effettuate con jQuery o con l'API nativa `fetch`. Queste richieste vengono mostrate come righe aggiuntive nella barra di Tracy, il che rende il debug AJAX semplice e comodo.

Se non volete catturare automaticamente le richieste AJAX, potete disattivare questa funzione impostando la variabile JavaScript:

```js
window.TracyAutoRefresh = false;
```

Per monitorare manualmente determinate richieste AJAX, aggiungete l'header HTTP `X-Tracy-Ajax` con il valore restituito da `Tracy.getAjaxHeader()`. Ecco un esempio d'uso con la funzione `fetch`:

```js
fetch(url, {
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'X-Tracy-Ajax': Tracy.getAjaxHeader(),
    }
})
```

Questo approccio permette di fare il debug selettivo delle richieste AJAX.


Salvataggio dei dati
====================

Tracy sa mostrare i pannelli della barra e le Bluescreen anche per le richieste AJAX e i redirect. Tracy crea sessioni proprie, salva i dati in file temporanei propri e usa il cookie `tracy-session`.

Tracy si può anche configurare perché usi la sessione nativa di PHP, che va avviata prima di attivare Tracy:

```php
session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();
```

Se avviare la sessione richiede un'inizializzazione più complessa, potete avviare Tracy subito (così può gestire gli eventuali errori) e inizializzare il gestore di sessione solo dopo. Alla fine comunicate a Tracy che la sessione è pronta all'uso con la funzione `dispatch()`:

```php
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// segue l'inizializzazione della sessione
// e l'avvio della sessione
session_start();

Debugger::dispatch();
```

La funzione `setSessionStorage()` esiste dalla versione 2.9; prima Tracy usava sempre la sessione nativa di PHP.


Scrubber personalizzato
=======================

Lo Scrubber è un filtro che impedisce ai dati sensibili di uscire dai dump, per esempio password o credenziali. Il filtro viene chiamato per ogni elemento dell'array o dell'oggetto sottoposto a dump e restituisce `true` se il valore è sensibile. In tal caso al posto del valore viene stampato `*****`.

```php
// impedisce il dump dei valori di chiavi e proprietà come `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD` ecc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// lo usiamo per tutti i dump dentro la BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Logger personalizzato
=====================

Possiamo creare un logger personalizzato che registrerà gli errori, le eccezioni non catturate e che verrà richiamato anche dal metodo `Tracy\Debugger::log()`. Il logger deve implementare l'interfaccia [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// invia una richiesta a Slack
	}
}
```

E poi lo attiviamo:

```php
Tracy\Debugger::setLogger(new SlackLogger);
```

Se usate tutto il Nette Framework, potete impostarlo nel file di configurazione NEON:

```neon
services:
	tracy.logger: SlackLogger
```


Integrazione con Monolog
------------------------

Il pacchetto Tracy offre un adattatore PSR-3, che permette di integrare [monolog/monolog](https://github.com/Seldaek/monolog).

```php
$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // scrive: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // scrive: [<TIMESTAMP>] main-channel.WARNING: warning [] []
```


Integrazione con Sentry
-----------------------

Potete inoltrare gli errori a un servizio come [Sentry |https://sentry.io] mantenendo il logging proprio di Tracy. L'idea è avvolgere il logger originale: il nuovo logger passa il messaggio a Sentry e poi lo delega al precedente, così i log su file e le notifiche per email continuano a funzionare.

```php
use Sentry\Severity;
use Tracy\Debugger;
use Tracy\ILogger;

class SentryLogger implements ILogger
{
	private ILogger $originalLogger;

	public function __construct(string $dsn)
	{
		$this->originalLogger = Debugger::getLogger();
		\Sentry\init(['dsn' => $dsn]);
	}

	public function log(mixed $value, string $level = self::INFO)
	{
		// invia a Sentry
		if ($severity = $this->getSeverity($level)) {
			$value instanceof \Throwable
				? \Sentry\captureException($value)
				: \Sentry\captureMessage((string) $value, $severity);
		}

		// mantiene il logging originale di Tracy (file, email)
		return $this->originalLogger->log($value, $level);
	}

	private function getSeverity(string $level): ?Severity
	{
		return match ($level) {
			ILogger::DEBUG => Severity::debug(),
			ILogger::INFO => Severity::info(),
			ILogger::WARNING => Severity::warning(),
			ILogger::ERROR, ILogger::EXCEPTION => Severity::error(),
			ILogger::CRITICAL => Severity::fatal(),
			default => null,
		};
	}
}
```

Lo attivate come qualsiasi altro logger personalizzato:

```php
Debugger::setLogger(new SentryLogger('https://public@sentry.example.com/1'));
```

In un'applicazione Nette registratelo invece come servizio `tracy.logger`:

```neon
services:
	tracy.logger: SentryLogger('https://public@sentry.example.com/1')
```


nginx
=====

Se Tracy non funziona su nginx, probabilmente è configurato male. Se c'è qualcosa come:

```nginx
try_files $uri $uri/ /index.php;
```

cambiatelo in:

```nginx
try_files $uri $uri/ /index.php$is_args$args;
```

Ricette

Content Security Policy

Se il vostro sito usa la Content Security Policy (CSP), dovrete aggiungere alla direttiva script-src i valori 'nonce-<valore>' e 'strict-dynamic' perché Tracy funzioni correttamente. Alcuni plugin di terze parti possono richiedere altre direttive. Il nonce non è supportato nella direttiva style-src; se usate questa direttiva, dovete aggiungere 'unsafe-inline', cosa che però andrebbe evitata in modalità produzione.

Esempio di configurazione per il Nette Framework:

http:
	csp:
		script-src: [nonce, strict-dynamic]

Esempio in PHP puro:

$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");

Caricamento più veloce

L'integrazione di base è semplice. Se però nella vostra pagina web ci sono script bloccanti che si caricano lentamente, possono rallentare il caricamento di Tracy. La soluzione è mettere nel template <?php Tracy\Debugger::renderLoader() ?> prima di qualsiasi script:

<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
</head>

Individuare la sorgente dell'output

Vi siete mai imbattuti in Cannot modify header information – headers already sent? Compare quando qualcosa (uno spazio sperduto, una riga vuota o un BOM all'inizio di un file) viene inviato al browser prima che il vostro codice imposti un header HTTP o avvii una sessione. Trovare il colpevole è noioso.

Vi aiuta Tracy\OutputDebugger. Attivatelo come primissima cosa nel programma:

Tracy\OutputDebugger::enable();

Sorveglia tutto l'output e alla fine della pagina stampa l'elenco di ogni punto da cui è stato inviato dell'output, con il file, la riga e un link che lo apre nel vostro editor. Viene evidenziato anche un byte order mark (BOM) all'inizio del file, perché è una causa invisibile molto frequente del problema.

Debug delle richieste AJAX

Tracy cattura automaticamente le richieste AJAX effettuate con jQuery o con l'API nativa fetch. Queste richieste vengono mostrate come righe aggiuntive nella barra di Tracy, il che rende il debug AJAX semplice e comodo.

Se non volete catturare automaticamente le richieste AJAX, potete disattivare questa funzione impostando la variabile JavaScript:

window.TracyAutoRefresh = false;

Per monitorare manualmente determinate richieste AJAX, aggiungete l'header HTTP X-Tracy-Ajax con il valore restituito da Tracy.getAjaxHeader(). Ecco un esempio d'uso con la funzione fetch:

fetch(url, {
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'X-Tracy-Ajax': Tracy.getAjaxHeader(),
    }
})

Questo approccio permette di fare il debug selettivo delle richieste AJAX.

Salvataggio dei dati

Tracy sa mostrare i pannelli della barra e le Bluescreen anche per le richieste AJAX e i redirect. Tracy crea sessioni proprie, salva i dati in file temporanei propri e usa il cookie tracy-session.

Tracy si può anche configurare perché usi la sessione nativa di PHP, che va avviata prima di attivare Tracy:

session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

Se avviare la sessione richiede un'inizializzazione più complessa, potete avviare Tracy subito (così può gestire gli eventuali errori) e inizializzare il gestore di sessione solo dopo. Alla fine comunicate a Tracy che la sessione è pronta all'uso con la funzione dispatch():

Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// segue l'inizializzazione della sessione
// e l'avvio della sessione
session_start();

Debugger::dispatch();

La funzione setSessionStorage() esiste dalla versione 2.9; prima Tracy usava sempre la sessione nativa di PHP.

Scrubber personalizzato

Lo Scrubber è un filtro che impedisce ai dati sensibili di uscire dai dump, per esempio password o credenziali. Il filtro viene chiamato per ogni elemento dell'array o dell'oggetto sottoposto a dump e restituisce true se il valore è sensibile. In tal caso al posto del valore viene stampato *****.

// impedisce il dump dei valori di chiavi e proprietà come `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD` ecc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// lo usiamo per tutti i dump dentro la BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Logger personalizzato

Possiamo creare un logger personalizzato che registrerà gli errori, le eccezioni non catturate e che verrà richiamato anche dal metodo Tracy\Debugger::log(). Il logger deve implementare l'interfaccia Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// invia una richiesta a Slack
	}
}

E poi lo attiviamo:

Tracy\Debugger::setLogger(new SlackLogger);

Se usate tutto il Nette Framework, potete impostarlo nel file di configurazione NEON:

services:
	tracy.logger: SlackLogger

Integrazione con Monolog

Il pacchetto Tracy offre un adattatore PSR-3, che permette di integrare monolog/monolog.

$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // scrive: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // scrive: [<TIMESTAMP>] main-channel.WARNING: warning [] []

Integrazione con Sentry

Potete inoltrare gli errori a un servizio come Sentry mantenendo il logging proprio di Tracy. L'idea è avvolgere il logger originale: il nuovo logger passa il messaggio a Sentry e poi lo delega al precedente, così i log su file e le notifiche per email continuano a funzionare.

use Sentry\Severity;
use Tracy\Debugger;
use Tracy\ILogger;

class SentryLogger implements ILogger
{
	private ILogger $originalLogger;

	public function __construct(string $dsn)
	{
		$this->originalLogger = Debugger::getLogger();
		\Sentry\init(['dsn' => $dsn]);
	}

	public function log(mixed $value, string $level = self::INFO)
	{
		// invia a Sentry
		if ($severity = $this->getSeverity($level)) {
			$value instanceof \Throwable
				? \Sentry\captureException($value)
				: \Sentry\captureMessage((string) $value, $severity);
		}

		// mantiene il logging originale di Tracy (file, email)
		return $this->originalLogger->log($value, $level);
	}

	private function getSeverity(string $level): ?Severity
	{
		return match ($level) {
			ILogger::DEBUG => Severity::debug(),
			ILogger::INFO => Severity::info(),
			ILogger::WARNING => Severity::warning(),
			ILogger::ERROR, ILogger::EXCEPTION => Severity::error(),
			ILogger::CRITICAL => Severity::fatal(),
			default => null,
		};
	}
}

Lo attivate come qualsiasi altro logger personalizzato:

Debugger::setLogger(new SentryLogger('https://public@sentry.example.com/1'));

In un'applicazione Nette registratelo invece come servizio tracy.logger:

services:
	tracy.logger: SentryLogger('https://public@sentry.example.com/1')

nginx

Se Tracy non funziona su nginx, probabilmente è configurato male. Se c'è qualcosa come:

try_files $uri $uri/ /index.php;

cambiatelo in:

try_files $uri $uri/ /index.php$is_args$args;