Come iniziare con Tracy

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

Attivare Tracy è facile. È sufficiente aggiungere queste due righe di codice, preferibilmente subito dopo il caricamento della libreria (come require 'vendor/autoload.php') e prima che qualsiasi output sia inviato al browser:

use Tracy\Debugger;

Debugger::enable();

La prima cosa che si noterà sul sito web è una barra Tracy.

(Se non si vede nulla, significa che Tracy è in modalità di produzione. Per motivi di sicurezza, Tracy è visibile solo su localhost. È possibile forzare l'esecuzione di Tracy in modalità di sviluppo passando Debugger::Development come primo parametro del metodo enable() ).

Il metodo enable() comporta la modifica del livello di segnalazione degli errori in E_ALL.

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

Per rilevare gli errori ortografici durante l'assegnazione a un oggetto, utilizziamo il tratto Nette\SmartObject.

Modalità di produzione e registrazione degli errori

Come si può vedere, Tracy è piuttosto eloquente. È apprezzabile in un ambiente di sviluppo, ma su un server di produzione sarebbe un disastro. Qualsiasi informazione di debug non può essere elencata. Per questo motivo, Tracy dispone di una funzionalità di rilevamento automatico dell'ambiente e di registrazione. Invece di mostrarsi, Tracy memorizza le informazioni in un file di log e mostra al visitatore un messaggio di errore del server comprensibile all'utente:

La modalità di output di produzione sopprime tutte le informazioni di debug inviate tramite dump() e, naturalmente, tutti i messaggi di errore generati da PHP. Quindi, anche se si dimentica dump($obj) nel codice sorgente, non ci si deve preoccupare sul server di produzione. Non si vedrà nulla.

La modalità di output è impostata dal primo parametro di Debugger::enable(). Si può specificare una costante Debugger::Production o Debugger::Development. Un'altra opzione è quella di impostare la modalità di sviluppo quando si accede all'applicazione da un indirizzo IP definito con un valore definito del cookie tracy-debug. La sintassi utilizzata per ottenere questo risultato è cookie-value@ip-address.

Se non viene specificato, viene utilizzato il valore predefinito Debugger::Detect. In questo caso, il sistema rileva un server in base all'indirizzo IP. La modalità di produzione viene scelta se l'applicazione è accessibile tramite un indirizzo IP pubblico. Un indirizzo IP locale porta alla modalità di sviluppo. Nella maggior parte dei casi non è necessario impostare la modalità. La modalità viene riconosciuta correttamente quando si avvia l'applicazione sul server locale o in produzione.

Nella modalità di produzione, Tracy cattura automaticamente tutti gli errori e le eccezioni in un registro di testo. A meno che non si specifichi diversamente, verrà memorizzato in log/error.log. La registrazione degli errori è estremamente utile. Immaginate che tutti gli utenti della vostra applicazione siano in realtà dei betatester. Stanno svolgendo gratuitamente un lavoro all'avanguardia nella ricerca di bug e sareste sciocchi se gettaste i loro preziosi rapporti nel cestino senza accorgervene.

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
}

Una directory per la registrazione degli errori può essere impostata dal secondo parametro del metodo enable():

Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');

Se si desidera che Tracy registri gli errori PHP come E_NOTICE o E_WARNING con informazioni dettagliate (rapporto HTML), impostare 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

Si applica alle ultime versioni della patch.

Porte

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

• Drupal 7
• Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim Framework
• Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
• Wordpress