Come iniziare con Tracy

La libreria Tracy è un utile strumento per i programmatori PHP di tutti i giorni. Aiuta a:

  • individuare e correggere rapidamente gli errori
  • registrare gli errori
  • scaricare le variabili
  • misurare il tempo di esecuzione di script/query
  • vedere il consumo di memoria

PHP è un linguaggio perfetto per la creazione di errori difficilmente rilevabili, perché offre una grande flessibilità ai programmatori. Per questo motivo, TracyDebugger è ancora più prezioso. È uno strumento di ultima generazione tra quelli diagnostici.

Se incontrate Tracy per la prima volta, credetemi, la vostra vita inizierà a dividersi in una prima di Tracy e una con lei. Benvenuti nella parte migliore!

Installazione e requisiti

Il modo migliore per installare Tracy è scaricare l'ultimo pacchetto o usare Composer:

composer require tracy/tracy

In alternativa, è possibile scaricare l'intero pacchetto o il file tracy.phar.

Utilizzo

Tracy viene attivato chiamando il metodo `Tracy\Debugger::enable()' il prima possibile all'inizio del programma, prima che venga inviato qualsiasi output:

use Tracy\Debugger;

require 'vendor/autoload.php'; // in alternativa tracy.phar

Debugger::enable();

La prima cosa che noterete nella pagina è la barra Tracy nell'angolo in basso a destra. Se non la si vede, significa che Tracy è in modalità di produzione. Questo perché Tracy è visibile solo su localhost per motivi di sicurezza. Per verificare se funziona, è possibile metterlo temporaneamente in modalità di sviluppo utilizzando il parametro Debugger::enable(Debugger::Development).

Barra Tracy

La barra Tracy è un pannello fluttuante. Viene visualizzata nell'angolo inferiore destro della pagina. È possibile spostarla con il mouse. Ricorda la sua posizione dopo il ricaricamento della pagina.

È possibile aggiungere altri pannelli utili alla barra Tracy. È possibile trovarne di interessanti nei componenti aggiuntivi o crearne di propri.

Se non si desidera visualizzare la barra Tracy, impostare:

Debugger::$showBar = false;

Visualizzazione di errori ed eccezioni

Sicuramente sapete come PHP segnala gli errori: c'è qualcosa del genere nel codice sorgente della pagina:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

o eccezione non catturata:

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Non è facile navigare in questo output. Se si abilita Tracy, sia gli errori che le eccezioni vengono visualizzati in una forma completamente diversa:

Il messaggio di errore urla letteralmente. È possibile vedere una parte del codice sorgente con la riga evidenziata in cui si è verificato l'errore. Un messaggio spiega chiaramente un errore. L'intero sito è interattivo, provatelo.

E sapete cosa? Gli errori fatali vengono catturati e visualizzati allo stesso modo. Non è necessario installare alcuna estensione (fare clic per un esempio dal vivo):

Errori come un errore di battitura nel nome di una variabile o il tentativo di aprire un file inesistente generano segnalazioni di livello E_NOTICE o E_WARNING. Questi errori possono essere facilmente trascurati e/o possono essere completamente nascosti nel layout grafico di una pagina web. Lasciate che sia Tracy a gestirli:

Oppure possono essere visualizzati come errori:

Debugger::$strictMode = true; // visualizza tutti gli errori
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // tutti gli errori tranne gli avvisi di deprecazione

Nota: Tracy, una volta attivato, cambia il livello di segnalazione degli errori in E_ALL. Se si desidera cambiare questo livello, farlo dopo aver chiamato enable().

Modalità di sviluppo e modalità di produzione

Come si può vedere, Tracy è piuttosto loquace, il che può essere apprezzato nell'ambiente di sviluppo, mentre sul server di produzione sarebbe un disastro. Questo perché lì non dovrebbero essere visualizzate informazioni di debug. Tracy ha quindi un rilevamento automatico dell'ambiente e se l'esempio viene eseguito su un server live, l'errore verrà registrato anziché visualizzato e il visitatore vedrà solo un messaggio di facile comprensione:

La modalità di produzione sopprime la visualizzazione di tutte le informazioni di debug inviate tramite dump() e, naturalmente, anche tutti i messaggi di errore generati da PHP. Quindi, se si è dimenticato qualche dump($obj) nel codice, non ci si deve preoccupare: sul server di produzione non verrà visualizzato nulla.

Come funziona il rilevamento automatico della modalità? La modalità è di sviluppo se l'applicazione è in esecuzione su localhost (cioè, l'indirizzo IP 127.0.0.1 o ::1) e non c'è alcun proxy (cioè, la sua intestazione HTTP). Altrimenti, viene eseguita in modalità produzione.

Se si desidera abilitare la modalità di sviluppo in altri casi, ad esempio per gli sviluppatori che accedono da un indirizzo IP specifico, è possibile specificarlo come parametro del metodo enable():

Debugger::enable('23.75.345.200'); // è possibile fornire anche un array di indirizzi IP

Si consiglia di combinare l'indirizzo IP con un cookie. Memorizzare un token segreto, ad esempio secret1234, nel cookie tracy-debug e, in questo modo, attivare la modalità di sviluppo solo per gli sviluppatori che accedono da un indirizzo IP specifico e che hanno il token citato nel cookie:

Debugger::enable('secret1234@23.75.345.200');

È anche possibile impostare direttamente la modalità di sviluppo/produzione utilizzando le costanti Debugger::Development o Debugger::Production come parametro del metodo enable().

Se si usa Nette Framework, si può vedere come impostare la modalità per esso, che verrà poi usata anche per Tracy.

Registrazione degli errori

In modalità di produzione, Tracy registra automaticamente tutti gli errori e le eccezioni in un registro di testo. Affinché la registrazione avvenga, è necessario impostare il percorso assoluto della cartella di log nella variabile $logDirectory o passarla come secondo parametro al metodo enable():

Debugger::$logDirectory = __DIR__ . '/log';

La registrazione degli errori è estremamente utile. Immaginate che tutti gli utenti della vostra applicazione siano in realtà dei beta tester che svolgono un lavoro di prim'ordine nel trovare gli errori gratuitamente, e sareste sciocchi a gettare le loro preziose segnalazioni nel cestino.

Se avete bisogno di registrare i vostri messaggi o le eccezioni catturate, usate il metodo log():

Debugger::log('Errore inatteso'); // messaggio di testo

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // registra l'eccezione
	// oppure
	Debugger::log($e, Debugger::ERROR); // invia anche una notifica via email
}

If you want Tracy to log PHP errors like E_NOTICE or E_WARNING with detailed information (HTML report), set Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Per un vero professionista il registro degli errori è una fonte cruciale di informazioni e vuole essere avvisato immediatamente di ogni nuovo errore. Tracy lo aiuta. È in grado di inviare un'e-mail per ogni nuovo record di errore. La variabile $email identifica dove inviare queste e-mail:

Debugger::$email = 'admin@example.com';

Se si utilizza l'intero Nette Framework, è possibile impostare questa variabile e altre nel file di configurazione.

Per proteggere la casella di posta elettronica dall'inondazione, Tracy invia un solo messaggio e crea un file email-sent. Quando uno sviluppatore riceve la notifica via e-mail, controlla il registro, corregge la sua applicazione e cancella il file di monitoraggio email-sent. Questo attiva nuovamente l'invio di e-mail.

Apertura dei file nell'editor

Quando viene visualizzata la pagina degli errori, è possibile fare clic sui nomi dei file e questi si apriranno nell'editor con il cursore sulla riga corrispondente. È anche possibile creare file (azione create file) o correggere bug in essi (azione fix it). Per fare ciò, è necessario configurare il browser e il sistema.

Versioni PHP supportate

Tracy compatibile con PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.2
Tracy 2.9 PHP 7.2 – 8.2
Tracy 2.8 PHP 7.2 – 8.1
Tracy 2.6 – 2.7 PHP 7.1 – 8.0
Tracy 2.5 PHP 5.4 – 7.4
Tracy 2.4 PHP 5.4 – 7.2

Si applica alle ultime versioni della patch.

Porte

Questo è un elenco di porte non ufficiali per altri framework e CMS: