Noțiuni de bază cu Tracy
************************

<div class=perex>

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

</div>


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 .[#toc-installation-and-requirements]
==========================================================

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ă utilizați Composer:

```shell
composer require tracy/tracy
```

Alternativ, puteți descărca întregul pachet sau fișierul [tracy.phar |https://github.com/nette/tracy/releases].


Utilizare .[#toc-usage]
=======================

Tracy este activat prin apelarea metodei `Tracy\Debugger::enable()' cât mai curând posibil la începutul programului, înainte de a fi trimisă orice ieșire:

```php
use Tracy\Debugger;

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

Debugger::enable();
```

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


Tracy Bar .[#toc-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.

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

Puteți adăuga alte panouri utile la bara de urmărire. Puteți găsi unele interesante în [addon-uri |https://componette.org] sau puteți să [vă creați propriile |extensions] panouri.

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

```php
Debugger::$showBar = false;
```


Vizualizarea erorilor și a excepțiilor .[#toc-visualization-of-errors-and-exceptions]
=====================================================================================

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

/--pre .{font-size: 90%}
<b>Parse error</b>:  syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>
\--

sau o excepție neînregistrată:

/--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/UI/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\UI\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 />
\--

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

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

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](https://nette.github.io/tracy/tracy-exception.html).

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

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

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:

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

Sau pot fi afișate ca erori:

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

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

Notă: Tracy, atunci când este activat, modifică nivelul de raportare a erorilor la E_ALL. Dacă doriți să modificați acest lucru, faceți acest lucru după ce ați apelat `enable()`.


Mod de dezvoltare vs. mod de producție .[#toc-development-vs-production-mode]
=============================================================================

După cum puteți vedea, Tracy este destul de vorbăreț, ceea ce poate fi apreciat în mediul de dezvoltare, în timp ce pe serverul de producție ar provoca un dezastru. Asta pentru că acolo nu ar trebui să fie afișate informații de depanare. Prin urmare, Tracy are **detecție automată a mediului** și dacă exemplul este rulat pe un server de producție, eroarea va fi înregistrată în loc să fie afișată, iar vizitatorul va vedea doar un mesaj ușor de utilizat:

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

Modul de producție suprimă afișarea tuturor informațiilor de depanare trimise cu ajutorul funcției [dump() |dumper] și, bineînțeles, a tuturor mesajelor de eroare generate de PHP. Așadar, dacă ați uitat ceva `dump($obj)` în cod, nu trebuie să vă faceți griji, nimic nu va fi afișat pe serverul de producție.

Cum funcționează autodetecția modului? Modul este dezvoltare dacă aplicația rulează pe localhost (adică adresa IP `127.0.0.1` sau `::1`) și nu există un proxy (adică antetul său HTTP). În caz contrar, se execută în modul de producție.

Dacă doriți să activați modul de dezvoltare în alte cazuri, de exemplu, pentru dezvoltatorii care accesează de la o anumită adresă IP, îl puteți specifica ca parametru al metodei `enable()`:

```php
Debugger::enable('23.75.345.200'); // puteți furniza, de asemenea, o matrice de adrese IP
```

Vă recomandăm cu siguranță să combinați adresa IP cu un cookie. Stocați un token secret, de exemplu, `secret1234`, în cookie-ul `tracy-debug` și, în acest fel, activați modul de dezvoltare numai pentru dezvoltatorii care accesează de la o anumită adresă IP și care au token-ul menționat în cookie:

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

De asemenea, puteți seta direct modul de dezvoltare/producție folosind constantele `Debugger::Development` sau `Debugger::Production` ca parametru al metodei `enable()`.

.[note]
Dacă utilizați Nette Framework, consultați [modul de setare a modului pentru acesta |application:bootstrap#Development vs Production Mode], care va fi utilizat și pentru Tracy.


Înregistrarea erorilor .[#toc-error-logging]
============================================

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

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

Înregistrarea erorilor este extrem de utilă. Imaginați-vă că toți utilizatorii aplicației dvs. sunt de fapt testeri beta care fac o muncă de top în găsirea erorilor în mod gratuit și că ați fi prost să aruncați rapoartele lor valoroase la coșul de gunoi fără să le observați.

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

```php
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
}
```

If you want Tracy to log PHP errors like `E_NOTICE` or `E_WARNING` with detailed information (HTML report), set `Debugger::$logSeverity`:

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

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

Dacă folosiți întregul Nette Framework, puteți seta această variabilă și altele în [fișierul de configurare |nette:configuring].

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 .[#toc-opening-files-in-the-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 |open-files-in-ide].


Versiuni PHP acceptate .[#toc-supported-php-versions]
=====================================================

| Tracy | compatibil cu PHP
|-----------|--------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.3
| 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 .[#toc-ports]
=====================

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

- [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)