Ricette

Politica di sicurezza dei contenuti

Se il proprio sito utilizza i Criteri di sicurezza dei contenuti, è necessario aggiungere i tag 'nonce-<value>' e 'strict-dynamic' a script-src perché Tracy funzioni correttamente. Alcuni plugin di terze parti potrebbero richiedere direttive aggiuntive. Nonce non è supportato dalla direttiva style-src; se si usa questa direttiva, è necessario aggiungere 'unsafe-inline', ma questo dovrebbe essere evitato in modalità di produzione.

Esempio di configurazione per 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, ma se nella pagina web sono presenti script di blocco lenti, questi possono rallentare il caricamento di Tracy. La soluzione è inserire <?php Tracy\Debugger::renderLoader() ?> nel template 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>

Debug delle richieste AJAX

Tracy cattura automaticamente le richieste AJAX effettuate con jQuery o con l'API nativa fetch. Queste richieste vengono visualizzate come righe aggiuntive nella barra di Tracy, consentendo un debug AJAX facile e conveniente.

Se non si desidera catturare automaticamente le richieste AJAX, è possibile disabilitare questa funzione impostando la variabile JavaScript:

window.TracyAutoRefresh = false;

Per il monitoraggio manuale di specifiche richieste AJAX, aggiungete l'intestazione HTTP X-Tracy-Ajax con il valore restituito da Tracy.getAjaxHeader(). Ecco un esempio di utilizzo con la funzione fetch:

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

Questo approccio consente un debug selettivo delle richieste AJAX.

Memorizzazione dei dati

Tracy può visualizzare pannelli a barre e Bluescreen per le richieste AJAX e i reindirizzamenti. Tracy crea le proprie sessioni, memorizza i dati nei propri file temporanei e utilizza il cookie tracy-session.

Tracy può anche essere configurato per utilizzare una sessione PHP nativa, che viene avviata prima dell'attivazione di Tracy:

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

Nel caso in cui l'avvio di una sessione richieda un'inizializzazione più complessa, è possibile avviare Tracy immediatamente (in modo che possa gestire eventuali errori), quindi inizializzare il gestore della sessione e infine informare Tracy che la sessione è pronta per essere utilizzata utilizzando la funzione dispatch():

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

// seguito dall'inizializzazione della sessione
// e avviare la sessione
session_start();

Debugger::dispatch();

La funzione setSessionStorage() esiste dalla versione 2.9, prima di allora Tracy utilizzava sempre la sessione nativa di PHP.

Scrubber personalizzato

Scrubber è un filtro che impedisce la fuoriuscita di dati sensibili dai dump, come password o credenziali. Il filtro viene richiamato per ogni elemento dell'array o dell'oggetto scaricato e restituisce true se il valore è sensibile. In questo caso, al posto del valore viene stampato *****.

// evita di scaricare i valori delle chiavi e le 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 all'interno di BlueScreen.
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Logger personalizzato

Possiamo creare un logger personalizzato per registrare gli errori, le eccezioni non catturate e anche per essere chiamato da Tracy\Debugger::log(). Il logger implementa 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 utilizziamo il Nette Framework completo, possiamo impostarlo nel file di configurazione di NEON:

services:
	tracy.logger: SlackLogger

Integrazione Monolog

Il pacchetto Tracy fornisce un adattatore PSR-3 che consente l'integrazione di 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 [] []

nginx

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

try_files $uri $uri/ /index.php;

cambiatelo in

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

Nette Documentation Preview