Iniziare con Tracy

La libreria Tracy è un utile aiuto quotidiano per il programmatore PHP. Ti aiuterà a:

  • individuare e correggere rapidamente gli errori
  • loggare gli errori
  • stampare le variabili
  • misurare il tempo degli script e delle query del database
  • monitorare l'utilizzo della memoria

PHP è un linguaggio fatto apposta per creare errori difficili da individuare, poiché offre agli sviluppatori una notevole libertà. Questo rende lo strumento di debug Tracy ancora più prezioso. Tra gli strumenti diagnostici per PHP, rappresenta l'apice assoluto.

Se oggi incontri Tracy per la prima volta, credimi, la tua vita inizierà a dividersi tra quella prima di Tracy e quella con lei. Benvenuto nella parte migliore!

Installazione

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

composer require tracy/tracy

Puoi anche scaricare l'intero pacchetto come file tracy.phar.

Utilizzo

Attiviamo Tracy chiamando il metodo Tracy\Debugger::enable() il prima possibile all'inizio del programma, prima di inviare qualsiasi output:

use Tracy\Debugger;

require 'vendor/autoload.php'; // o tracy.phar

Debugger::enable();

La prima cosa che noterai sulla pagina è la Tracy Bar nell'angolo in basso a destra. Se non la vedi, potrebbe significare che Tracy è in esecuzione in modalità produzione. Infatti, per motivi di sicurezza, Tracy è visibile solo su localhost. Per testare se funziona, puoi temporaneamente passare alla modalità sviluppo usando il parametro Debugger::enable(Debugger::Development).

Tracy Bar

La Tracy Bar è un pannello flottante che appare nell'angolo in basso a destra della pagina. Possiamo spostarlo con il mouse e ricorderà la sua posizione dopo il ricaricamento della pagina.

È possibile aggiungere altri pannelli utili alla Tracy Bar. Ne troverai molti nei componenti aggiuntivi, o puoi persino scriverne di tuoi.

Se non vuoi visualizzare la Tracy Bar, imposta:

Debugger::$showBar = false;

Visualizzazione di errori ed eccezioni

Sicuramente sai bene come PHP segnala gli errori: stampa qualcosa del genere nel codice sorgente della pagina:

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

o in caso di 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/Presentation/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presentation\Sign\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 è esattamente facile orientarsi in un output del genere. Se attiviamo Tracy, l'errore o l'eccezione vengono visualizzati in una forma completamente diversa:

Il messaggio di errore urla letteralmente. Vediamo una parte del codice sorgente con la riga evidenziata dove si è verificato l'errore e l'informazione Call to undefined method Nette\Http\User::isLogedIn() spiega chiaramente di che errore si tratta. Inoltre, l'intera pagina è interattiva, possiamo cliccare per ottenere maggiori dettagli. Provalo.

E sai una cosa? In questo modo cattura e visualizza anche gli errori fatali. Senza la necessità di installare alcuna estensione.

Errori come un refuso nel nome di una variabile o il tentativo di aprire un file inesistente generano messaggi di livello E_NOTICE o E_WARNING. Questi possono essere facilmente trascurati nella grafica della pagina, potrebbero addirittura non essere visibili affatto (a meno che non si guardi il codice sorgente).

Oppure possono essere visualizzati allo stesso modo degli errori:

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

Nota: Dopo l'attivazione, Tracy cambia il livello di segnalazione degli errori in E_ALL. Se vuoi cambiare questo valore, fallo dopo aver chiamato enable().

Modalità Sviluppo vs Produzione

Come puoi vedere, Tracy è piuttosto loquace, il che può essere apprezzato in un ambiente di sviluppo, mentre su un server di produzione causerebbe un vero disastro. Infatti, nessuna informazione di debug deve essere stampata lì. Tracy dispone quindi di rilevamento automatico dell'ambiente e se eseguiamo l'esempio su un server live, l'errore verrà loggato invece di essere visualizzato e il visitatore vedrà solo un messaggio comprensibile per l'utente:

La modalità produzione sopprime la visualizzazione di tutte le informazioni di debug che inviamo tramite dump(), e ovviamente anche di tutti i messaggi di errore generati da PHP. Quindi, se hai dimenticato qualche dump($obj) nel codice, non devi preoccuparti, nulla verrà stampato sul server di produzione.

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

Se vogliamo abilitare la modalità sviluppo anche in altri casi, ad esempio per i programmatori che accedono da un indirizzo IP specifico, lo specifichiamo come parametro del metodo enable():

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

Consigliamo vivamente di combinare l'indirizzo IP con un cookie. Salviamo un token segreto nel cookie tracy-debug, ad esempio secret1234, e in questo modo attiviamo la modalità sviluppo solo per i programmatori che accedono da un indirizzo IP specifico e che hanno il token menzionato nel cookie:

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

Possiamo anche impostare direttamente la modalità sviluppo/produzione utilizzando la costante Debugger::Development o Debugger::Production come parametro del metodo enable().

Se utilizzi Nette Framework, guarda come impostare la modalità per esso e questa verrà quindi utilizzata anche per Tracy.

Logging degli errori

In modalità produzione, Tracy logga automaticamente tutti gli errori e le eccezioni catturate in un log di testo. Affinché il logging funzioni, dobbiamo impostare il percorso assoluto della directory di log nella variabile $logDirectory o passarlo come secondo parametro del metodo enable():

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

Il logging degli errori è estremamente utile. Immagina che tutti gli utenti della tua applicazione siano in realtà beta tester che svolgono gratuitamente un lavoro eccellente nella ricerca di errori, e sarebbe sciocco da parte tua gettare i loro preziosi report nel cestino senza prenderne nota.

Se abbiamo bisogno di loggare un messaggio personalizzato o un'eccezione che abbiamo catturato, usiamo il metodo log():

Debugger::log('Si è verificato un errore imprevisto'); // messaggio di testo

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // è possibile loggare anche l'eccezione
	// o
	Debugger::log($e, Debugger::ERROR); // invia anche una notifica via e-mail
}

Se vuoi che Tracy logghi gli errori PHP come E_NOTICE o E_WARNING con informazioni dettagliate (report HTML), imposta Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Per un vero professionista, l'error log è una fonte chiave di informazioni e vuole essere informato immediatamente di ogni nuovo errore. Tracy viene incontro a questo, poiché può informare via e-mail di una nuova voce nel log. Specifichiamo dove inviare le e-mail con la variabile $email:

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

Se utilizzi l'intero Nette Framework, questo e altro possono essere impostati nel file di configurazione.

Tuttavia, per non inondare la tua casella di posta elettronica, invia sempre solo un messaggio e crea il file email-sent. Dopo aver ricevuto la notifica via e-mail, lo sviluppatore controlla il log, corregge l'applicazione ed elimina il file di monitoraggio, riattivando così l'invio delle e-mail.

Apertura nell'editor

Quando viene visualizzata la pagina di errore, è possibile fare clic sui nomi dei file e questi si apriranno nel tuo editor con il cursore sulla riga corrispondente. È anche possibile creare file (azione create file) o correggere errori in essi (azione fix it). Affinché funzioni, è sufficiente configurare il browser e il sistema.

Versioni PHP supportate

Tracy compatibile con PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.4
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

Valido per l'ultima versione patch.

Port

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