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
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
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:
- 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