Noțiuni de bază cu Tracy

Biblioteca Tracy este un ajutor util pentru programatorii PHP obișnuiți. Aceasta vă ajută să:

  • să detectați și să corectați rapid erorile
  • înregistrați erorile
  • să aruncați variabilele
  • să măsurați timpul de execuție a scripturilor/interogărilor
  • să vedeți consumul de memorie

PHP este un limbaj perfect pentru a face erori greu de detectat, deoarece oferă o mare flexibilitate programatorilor. Tracy\Debugger este mai valoros din acest motiv. Este un instrument suprem printre cele de diagnosticare. Dacă o întâlnești pe Tracy pentru prima dată, crede-mă, viața ta începe să fie împărțită în una înainte de Tracy și una cu ea. Bine ați venit în partea bună!

Instalare și cerințe

Cel mai bun mod de a instala Tracy este să descărcați cel mai recent pachet sau să utilizați Composer:

composer require tracy/tracy

Alternativ, puteți descărca întregul pachet sau fișierul tracy.phar.

Utilizare

Activarea lui Tracy este ușoară. Pur și simplu adăugați aceste două linii de cod, de preferință imediat după încărcarea bibliotecii (cum ar fi require 'vendor/autoload.php') și înainte ca orice ieșire să fie trimisă în browser:

use Tracy\Debugger;

Debugger::enable();

Primul lucru pe care îl veți observa pe site este o bară Tracy.

(Dacă nu vedeți nimic, înseamnă că Tracy rulează în modul de producție. Din motive de securitate, Tracy este vizibil doar pe localhost. Puteți forța Tracy să ruleze în modul de dezvoltare trecând Debugger::Development ca prim parametru al metodei enable() ).

Metoda enable() presupune schimbarea nivelului de raportare a erorilor la E_ALL.

Tracy Bar

Tracy Bar este un panou plutitor. Acesta este afișat în colțul din dreapta jos al unei pagini. O puteți muta cu ajutorul mouse-ului. Își va reține poziția după reîncărcarea paginii.

Puteți adăuga alte panouri utile la bara de urmărire. Puteți găsi unele interesante în addon-uri sau puteți să vă creați propriile panouri.

Dacă nu doriți să afișați Tracy Bar, setați:

Debugger::$showBar = false;

Vizualizarea erorilor și a excepțiilor

Cu siguranță, știți cum raportează PHP erorile: există ceva de genul acesta în codul sursă al paginii:

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

sau o excepție neînregistrată:

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

Nu este atât de ușor să navigați prin această ieșire. Dacă activați Tracy, atât erorile, cât și excepțiile sunt afișate într-o formă complet diferită:

Mesajul de eroare strigă literalmente. Puteți vedea o parte din codul sursă cu linia evidențiată în care a apărut eroarea. Un mesaj explică în mod clar o eroare. Întregul site este interactiv, încercați-l.

Și știți ce? Erorile fatale sunt capturate și afișate în același mod. Nu este nevoie să instalați nicio extensie (faceți clic pentru un exemplu live):

Erori precum o greșeală de scriere în numele unei variabile sau o încercare de a deschide un fișier inexistent generează rapoarte de nivel E_NOTICE sau E_WARNING. Acestea pot fi trecute cu ușurință cu vederea și/sau pot fi complet ascunse în aspectul grafic al unei pagini web. Lăsați-l pe Tracy să le gestioneze:

Sau pot fi afișate ca erori:

Debugger::$strictMode = true; // afișarea tuturor erorilor
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // toate erorile, cu excepția notificărilor depreciate

Pentru a detecta greșelile de ortografie la atribuirea unui obiect, folosim trăsătura Nette\SmartObject.

Modul de producție și jurnalizarea erorilor

După cum puteți vedea, Tracy este destul de elocvent. Este apreciat într-un mediu de dezvoltare, dar pe un server de producție, ar provoca un dezastru. Orice informație de depanare nu poate fi listată acolo. Prin urmare, Tracy are o funcționalitate de autodetecție a mediului și de logare. În loc să se afișeze, Tracy stochează informațiile într-un fișier jurnal și arată vizitatorului un mesaj de eroare a serverului inteligibil pentru utilizator:

Modul de ieșire de producție suprimă toate informațiile de depanare care sunt trimise prin intermediul funcției dump() și, bineînțeles, toate mesajele de eroare generate de PHP. Astfel, chiar dacă uitați dump($obj) în codul sursă, nu trebuie să vă faceți griji în legătură cu acest lucru pe serverul de producție. Nu se va vedea nimic.

Modul de ieșire este setat de primul parametru al Debugger::enable(). Puteți specifica fie o constantă Debugger::Production, fie Debugger::Development. O altă opțiune este să o configurați în așa fel încât modul de dezvoltare să fie activat atunci când aplicația este accesată de la o adresă IP definită cu o valoare definită a cookie-ului tracy-debug. Sintaxa utilizată pentru a realiza acest lucru este cookie-value@ip-address.

Dacă nu este specificată, se utilizează valoarea implicită Debugger::Detect. În acest caz, sistemul detectează un server după adresa IP. Modul de producție este ales în cazul în care o aplicație este accesată printr-o adresă IP publică. O adresă IP locală conduce la modul de dezvoltare. Nu este necesar să setați modul în majoritatea cazurilor. Modul este recunoscut corect atunci când lansați aplicația pe serverul local sau în producție.

În modul de producție, Tracy captează automat toate erorile și excepțiile într-un jurnal de text. Cu excepția cazului în care nu specificați altfel, acesta va fi stocat în log/error.log. Această înregistrare a erorilor este extrem de utilă. Imaginați-vă că toți utilizatorii aplicației dvs. sunt de fapt betatesteri. Aceștia fac o muncă de ultimă oră pe gratis atunci când vânează erori și ați fi prost dacă ați arunca rapoartele lor valoroase la coșul de reciclare fără să le observați.

Dacă aveți nevoie să vă înregistrați propriile mesaje sau excepții capturate, utilizați metoda log():

Debugger::log('Unexpected error'); // mesaj text

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // excepție de jurnal
	// sau
	Debugger::log($e, Debugger::ERROR); // trimite, de asemenea, o notificare prin e-mail
}

Un director pentru înregistrarea erorilor poate fi setat prin intermediul celui de-al doilea parametru al metodei enable():

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

Dacă doriți ca Tracy să înregistreze erori PHP precum E_NOTICE sau E_WARNING cu informații detaliate (raport HTML), setați Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Pentru un adevărat profesionist, jurnalul de erori este o sursă crucială de informații și dorește să fie anunțat imediat despre orice nouă eroare. Tracy îl ajută. Ea este capabilă să trimită un e-mail pentru fiecare înregistrare de eroare nouă. Variabila $email identifică unde să trimită aceste e-mailuri:

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

Dacă folosiți întregul Nette Framework, puteți seta această variabilă și altele în fișierul de configurare.

Pentru a vă proteja căsuța de e-mail de inundații, Tracy trimite numai un mesaj și creează un fișier email-sent. Când un dezvoltator primește notificarea prin e-mail, el verifică jurnalul, își corectează aplicația și șterge fișierul de monitorizare email-sent. Acest lucru activează din nou trimiterea de e-mail.

Deschiderea fișierelor în editor

Atunci când este afișată pagina de erori, puteți face clic pe numele fișierelor, iar acestea se vor deschide în editorul dvs. cu cursorul pe linia corespunzătoare. Fișierele pot fi, de asemenea, create (acțiunea create file) sau pot fi corectate erori în ele (acțiunea fix it). Pentru a face acest lucru, trebuie să configurați browserul și sistemul.

Versiuni PHP acceptate

Tracy compatibil cu 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

Se aplică la cele mai recente versiuni de patch-uri.

Porturi

Aceasta este o listă de portări neoficiale către alte cadre și CMS: