Introducere în Tracy

********************

<div class=perex>

Biblioteca Tracy este un ajutor zilnic util pentru programatorul PHP. Vă va ajuta să:

- detectați și corectați rapid erorile

- logați erorile

- afișați variabilele

- măsurați timpul de execuție al scripturilor și interogărilor de baze de date

- monitorizați cerințele de memorie

</div>

PHP este un limbaj predispus la crearea de erori greu de detectat, deoarece oferă dezvoltatorilor o libertate considerabilă. Cu atât mai valoros este instrumentul de depanare Tracy. Printre instrumentele de diagnosticare pentru PHP, reprezintă vârful absolut.

Dacă întâlniți Tracy pentru prima dată astăzi, credeți că viața dvs. se va împărți în cea dinainte de Tracy și cea cu ea. Bine ați venit în partea mai bună!

Instalare

=========

Cel mai bun mod de a instala Tracy este să [descărcați cel mai recent pachet](https://github.com/nette/tracy/releases) sau să folosiți Composer:

```shell

composer require tracy/tracy

```

Puteți, de asemenea, să descărcați întregul pachet ca fișier [tracy.phar |https://github.com/nette/tracy/releases].

Utilizare

=========

Activăm Tracy apelând metoda `Tracy\Debugger::enable()` cât mai devreme posibil la începutul programului, înainte de a trimite orice ieșire:

```php

use Tracy\Debugger;

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

Debugger::enable();

```

Primul lucru pe care îl veți observa pe pagină este Tracy Bar în colțul din dreapta jos. Dacă nu îl vedeți, poate însemna că Tracy rulează în modul de producție. Tracy este, din motive de securitate, vizibilă doar pe localhost. Pentru a testa dacă funcționează, o puteți comuta temporar în modul de dezvoltare folosind parametrul `Debugger::enable(Debugger::Development)`.

Tracy Bar

=========

Tracy Bar este un panou plutitor care apare în colțul din dreapta jos al paginii. Îl putem muta cu mouse-ul și își va aminti poziția după reîncărcarea paginii.

[* tracy-bar.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

În Tracy Bar se pot adăuga alte panouri utile. Multe dintre ele le găsiți în [suplimente |https://componette.org] sau chiar [puteți scrie propriul dvs |extensions].

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

```php

Debugger::$showBar = false;

```

Vizualizarea erorilor și excepțiilor

====================================

Cu siguranță știți cum PHP anunță erorile: în codul sursă al paginii afișează ceva de genul:

/--pre .{font-size: 90%}

<b>Parse error</b>: syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>

\--

sau în cazul unei excepții necapturate:

/--pre .{font-size: 90%}

<b>Fatal error</b>: 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 <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />

\--

Orientarea într-o astfel de afișare nu este tocmai ușoară. Dacă activăm Tracy, eroarea sau excepția se afișează într-o formă complet diferită:

[* tracy-exception.webp .{url:-} *]

Mesajul de eroare literalmente țipă. Vedem o parte din codul sursă cu linia evidențiată unde a apărut eroarea și informația *Call to undefined method Nette\Http\User::isLogedIn()* explică clar despre ce eroare este vorba. Întreaga pagină este, de asemenea, interactivă, putem face clic pentru a vedea mai multe detalii. [Încercați |https://nette.github.io/tracy/tracy-exception.html].

Și știți ce? În acest mod capturează și afișează chiar și erorile fatale. Fără a fi nevoie să instalați vreo extensie.

[* tracy-error.webp .{url:-} *]

Erorile precum greșelile de tipar în numele variabilelor sau încercarea de a deschide un fișier inexistent generează rapoarte de nivel E_NOTICE sau E_WARNING. Acestea pot fi ușor trecute cu vederea în grafica paginii, ba chiar pot să nu fie vizibile deloc (decât dacă priviți codul paginii).

[* tracy-notice2.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Sau pot fi afișate la fel ca erorile:

```php

Debugger::$strictMode = true; // afișează toate erorile

Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // toate erorile, cu excepția notificărilor de depreciere

```

[* tracy-notice.webp .{url:-} *]

Notă: Tracy, după activare, schimbă nivelul de raportare a erorilor la E_ALL. Dacă doriți să schimbați această valoare, faceți acest lucru după apelarea `enable()`.

Mod dezvoltare vs producție

===========================

După cum vedeți, Tracy este destul de vorbăreață, ceea ce poate fi apreciat în mediul de dezvoltare, în timp ce pe serverul de producție ar provoca un adevărat dezastru. Acolo nu trebuie afișate nicio informație de depanare. Tracy dispune, prin urmare, de **autodetecție a mediului** și dacă exemplul este rulat pe un server live, eroarea este logată în loc să fie afișată, iar vizitatorul vede doar un mesaj ușor de înțeles pentru utilizator:

[* tracy-error2.webp .{url:-} *]

Modul de producție suprimă afișarea tuturor informațiilor de depanare pe care le trimitem folosind [dump() |dumper] și, desigur, a tuturor mesajelor de eroare generate de PHP. Deci, dacă ați uitat vreun `dump($obj)` în cod, nu trebuie să vă faceți griji, pe serverul de producție nu se va afișa nimic.

Cum funcționează autodetecția modului? Modul este de dezvoltare atunci când aplicația este rulată pe localhost (adică adresa IP `127.0.0.1` sau `::1`) și nu există un proxy prezent (adică antetul său HTTP). Altfel, rulează în modul de producție.

Dacă dorim să permitem modul de dezvoltare și în alte cazuri, de exemplu pentru programatorii care accesează de la o anumită adresă IP, o specificăm ca parametru al metodei `enable()`:

```php

Debugger::enable('23.75.345.200'); // se poate specifica și un array de adrese IP

```

Recomandăm cu tărie combinarea adresei IP cu un cookie. În cookie-ul `tracy-debug` stocăm un token secret, de ex. `secret1234`, și în acest mod activăm modul de dezvoltare doar pentru programatorii care accesează de la o anumită adresă IP și au tokenul menționat în cookie:

```php

Debugger::enable('[email protected]');

```

Putem, de asemenea, să setăm direct modul de dezvoltare/producție folosind constantele `Debugger::Development` sau `Debugger::Production` ca parametru al metodei `enable()`.

.[note]

Dacă utilizați Nette Framework, vedeți cum să [setați modul pentru acesta |application:bootstrapping#Modul de dezvoltare vs producție] și acesta va fi apoi utilizat și pentru Tracy.

Logarea erorilor

================

În modul de producție, Tracy înregistrează automat toate erorile și excepțiile capturate într-un log text. Pentru ca logarea să aibă loc, trebuie să setăm calea absolută către directorul de logare în variabila `$logDirectory` sau să o transmitem ca al doilea parametru al metodei `enable()`:

```php

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

```

Logarea erorilor este, de altfel, extrem de utilă. Imaginați-vă că toți utilizatorii aplicației dvs. sunt, de fapt, beta-testeri care fac gratuit o muncă excelentă în găsirea erorilor și ați face o prostie dacă ați arunca rapoartele lor valoroase neobservate la coșul de gunoi.

Dacă avem nevoie să logăm un mesaj personalizat sau o excepție capturată de noi, folosim metoda `log()`:

```php

Debugger::log('A apărut o eroare neașteptată'); // mesaj text

try {

criticalOperation();

} catch (Exception $e) {

Debugger::log($e); // se poate loga și excepția

// sau

Debugger::log($e, Debugger::ERROR); // trimite și o notificare prin e-mail

}

```

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

```php

Debugger::$logSeverity = E_NOTICE | E_WARNING;

```

Pentru un adevărat profesionist, logul de erori este o sursă cheie de informații și dorește să fie informat imediat despre fiecare nouă eroare. Tracy îi vine în ajutor, deoarece poate informa prin e-mail despre o nouă înregistrare în log. Unde să trimitem e-mailurile specificăm prin variabila `$email`:

```php

Debugger::$email = '[email protected]';

```

Dacă utilizați întregul Nette Framework, puteți seta aceasta și alte setări în [fișierul de configurare |nette:configuring].

Pentru a nu vă inunda căsuța de e-mail, trimite întotdeauna **doar un singur mesaj** și creează fișierul `email-sent`. Dezvoltatorul, după primirea notificării prin e-mail, verifică logul, corectează aplicația și șterge fișierul de monitorizare `email-sent`, reactivând astfel trimiterea e-mailurilor.

Deschiderea în editor

=====================

La afișarea paginii de eroare, se poate face clic pe numele fișierelor și acestea se vor deschide în editorul dvs. cu cursorul pe linia corespunzătoare. De asemenea, se pot crea fișiere (acțiunea `create file`) sau corecta erori în ele (acțiunea `fix it`). Pentru ca acest lucru să funcționeze, este suficient să [configurați browserul și sistemul |open-files-in-ide].

Versiuni PHP suportate

======================

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

Valabil pentru ultima versiune patch.

Porturi

=======

Aceasta este o listă de porturi neoficiale pentru alte framework-uri și CMS-uri:

- [Drupal 7](https://www.drupal.org/project/traced)

- Laravel framework: [recca0120/laravel-tracy](https://github.com/recca0120/laravel-tracy), [whipsterCZ/laravel-tracy](https://github.com/whipsterCZ/laravel-tracy)

- [OpenCart](https://github.com/BurdaPraha/oc_tracy)

- [ProcessWire CMS/CMF](https://github.com/adrianbj/TracyDebugger)

- [Slim Framework](https://github.com/runcmf/runtracy)

- Symfony framework: [kutny/tracy-bundle](https://github.com/kutny/tracy-bundle), [VasekPurchart/Tracy-Blue-Screen-Bundle](https://github.com/VasekPurchart/Tracy-Blue-Screen-Bundle)

- [Wordpress](https://github.com/ktstudio/WP-Tracy)