Tutorial

Content Security Policy

Se il tuo sito web utilizza Content Security Policy, dovrai aggiungere gli stessi 'nonce-<value>' e 'strict-dynamic' a script-src affinché Tracy funzioni correttamente. Alcuni componenti aggiuntivi di terze parti potrebbero richiedere impostazioni aggiuntive. Nonce non è supportato nella direttiva style-src; se utilizzi questa direttiva, devi aggiungere 'unsafe-inline', ma dovresti evitarlo in modalità 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'avvio è semplice, ma se hai script bloccanti a caricamento lento sulla tua pagina web, possono rallentare il caricamento di Tracy. La soluzione è posizionare <?php Tracy\Debugger::renderLoader() ?> nel tuo template prima di tutti gli 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>

Debugging delle richieste AJAX

Tracy cattura automaticamente le richieste AJAX create utilizzando jQuery o l'API nativa fetch. Le richieste vengono visualizzate nella barra di Tracy come righe aggiuntive, consentendo un debug AJAX facile e comodo.

Se non desideri catturare automaticamente le richieste AJAX, puoi disabilitare questa funzione impostando una variabile JavaScript:

window.TracyAutoRefresh = false;

Per monitorare manualmente specifiche richieste AJAX, aggiungi l'header 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 il debug selettivo delle richieste AJAX.

Archiviazione dati

Tracy può visualizzare pannelli nella barra di Tracy e Bluescreen per richieste AJAX e redirect. Tracy crea la propria sessione, memorizza i dati nei propri file temporanei e utilizza il cookie tracy-session.

Tracy può anche essere configurata per utilizzare la sessione PHP nativa, che avviamo prima di abilitare Tracy:

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

Nel caso in cui l'avvio della sessione richieda un'inizializzazione più complessa, puoi avviare Tracy immediatamente (in modo che possa gestire eventuali errori che si verificano), quindi inizializzare il gestore della sessione e infine informare Tracy che la sessione è pronta per l'uso utilizzando 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 di allora, Tracy utilizzava sempre la sessione PHP nativa.

Scrubber personalizzato

Lo Scrubber è un filtro che impedisce la fuga di dati sensibili durante il dump, come password o credenziali di accesso. Il filtro viene chiamato per ogni elemento dell'array o dell'oggetto dumpato e restituisce true se il valore è sensibile. In tal caso, viene stampato ***** al posto del valore.

// impedisce la stampa dei valori delle chiavi e delle 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 useremo per tutti i dump all'interno del BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Logger personalizzato

Possiamo creare il nostro logger personalizzato che registrerà errori, eccezioni non catturate e sarà anche invocato dal metodo 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 successivamente lo attiviamo:

Tracy\Debugger::setLogger(new SlackLogger);

Se utilizziamo il Nette Framework completo, puoi impostarlo nel file di configurazione NEON:

services:
	tracy.logger: SlackLogger

Integrazione di 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 sul tuo server nginx, probabilmente è configurato male. Se c'è qualcosa come questo nella configurazione:

try_files $uri $uri/ /index.php;

cambialo in:

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