Ismerkedés a Tracy-vel
**********************

<div class=perex>

A Tracy könyvtár hasznos mindennapi segédje a PHP programozónak. Segít Önnek:

- gyorsan felfedezni és javítani a hibákat
- hibákat naplózni
- változókat kiírni
- szkriptek és adatbázis-lekérdezések idejét mérni
- memóriaigényeket figyelni

</div>


A PHP egy olyan nyelv, amely tökéletesen alkalmas a nehezen felfedezhető hibák elkövetésére, mivel jelentős szabadságot ad a fejlesztőknek. Annál értékesebb a Tracy debuggoló eszköz. A PHP diagnosztikai eszközei között abszolút csúcsot képvisel.

Ha ma találkozik először a Tracy-vel, higgye el, hogy az élete ketté fog válni: a Tracy előtti és a vele való életre. Üdvözöljük a jobbik részben!


Telepítés
=========

A Tracy telepítésének legjobb módja a [legújabb csomag letöltése](https://github.com/nette/tracy/releases), vagy a Composer használata:

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

Letöltheti az egész csomagot [tracy.phar |https://github.com/nette/tracy/releases] fájlként is.


Használat
=========

A Tracy-t a `Tracy\Debugger::enable()` metódus hívásával aktiváljuk a program legelején, még bármilyen kimenet küldése előtt:

```php
use Tracy\Debugger;

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

Debugger::enable();
```

Az első dolog, amit észrevesz az oldalon, a Tracy Bar a jobb alsó sarokban. Ha nem látja, az jelentheti, hogy a Tracy éles/produkciós módban fut. A Tracy ugyanis biztonsági okokból csak localhoston látható. Annak tesztelésére, hogy működik-e, ideiglenesen átkapcsolhatja fejlesztői módba a `Debugger::enable(Debugger::Development)` paraméterrel.


Tracy Bar
=========

A Tracy Bar egy lebegő panel, amely az oldal jobb alsó sarkában jelenik meg. Egérrel mozgathatjuk, és az oldal újratöltése után emlékezni fog a pozíciójára.

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

A Tracy Barhoz további hasznos paneleket lehet hozzáadni. Sokat találhat a [kiegészítőkben |https://componette.org], vagy akár [írhatsz sajátot |extensions] is.

Ha nem szeretné megjeleníteni a Tracy Bart, állítsa be:

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


Hibák és kivételek vizualizációja
=================================

Bizonyára jól tudja, hogyan jelzi a PHP a hibákat: az oldal forráskódjába valami ilyesmit ír ki:

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

vagy el nem kapott kivétel esetén:

/--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 />
\--

Egy ilyen kimenetben eligazodni nem éppen könnyű. Ha bekapcsoljuk a Tracy-t, a hiba vagy kivétel teljesen más formában jelenik meg:

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

A hibaüzenet szó szerint kiabál. Látjuk a forráskód egy részletét a kiemelt sorral, ahol a hiba történt és a *Call to undefined method Nette\Http\User::isLogedIn()* információ érthetően magyarázza, milyen hibáról van szó. Az egész oldal ráadásul élő, átkattinthatunk további részletekre. [Próbáld ki |https://nette.github.io/tracy/tracy-exception.html].

És tudja mit? Így kapja el és jeleníti meg a fatális hibákat is. Anélkül, hogy bármilyen kiterjesztést telepíteni kellene.

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

Az olyan hibák, mint egy elgépelés a változó nevében vagy egy nem létező fájl megnyitásának kísérlete, E_NOTICE vagy E_WARNING szintű jelentéseket generálnak. Ezeket az oldal grafikájában könnyű figyelmen kívül hagyni, sőt, lehet, hogy egyáltalán nem láthatók (legfeljebb az oldal kódjának megtekintésével).

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

Vagy megjeleníthetők ugyanúgy, mint a hibák:

```php
Debugger::$strictMode = true; // jelenítsen meg minden hibát
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // minden hiba, kivéve a deprecate értesítéseket
```

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

Megjegyzés: A Tracy aktiválás után az E_ALL szintre változtatja a hibajelentési szintet. Ha ezt az értéket módosítani szeretné, tegye meg az `enable()` hívása után.


Fejlesztői vs éles/produkciós mód
=================================

Ahogy látja, a Tracy meglehetősen bőbeszédű, ami fejlesztői környezetben értékelhető, míg egy éles/produkciós szerveren kész katasztrófát okozna. Ott ugyanis semmilyen debuggolási információ nem íródhat ki. A Tracy ezért **környezet automatikus észlelésével** rendelkezik, és ha a példát éles szerveren futtatjuk, a hiba megjelenítés helyett naplózásra kerül, és a látogató csak egy felhasználóbarát üzenetet lát:

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

Az éles/produkciós mód elnyomja az összes debuggolási információ megjelenítését, amelyet a [dump() |dumper] segítségével küldünk ki, és természetesen az összes hibaüzenetet is, amelyet a PHP generál. Tehát ha a kódban elfelejtett néhány `dump($obj)`-ot, nem kell aggódnia, az éles/produkciós szerveren semmi sem fog kiíródni.

Hogyan működik a mód automatikus észlelése? A mód akkor fejlesztői, ha az alkalmazás localhoston fut (azaz `127.0.0.1` vagy `::1` IP-címen), és nincs jelen proxy (azaz annak HTTP fejléce). Egyébként éles/produkciós módban fut.

Ha engedélyezni szeretnénk a fejlesztői módot más esetekben is, például egy konkrét IP-címről hozzáférő programozóknak, adjuk meg azt az `enable()` metódus paramétereként:

```php
Debugger::enable('23.75.345.200'); // IP-címek tömbje is megadható
```

Határozottan javasoljuk az IP-cím és egy süti kombinálását. A `tracy-debug` sütibe mentsünk el egy titkos tokent, pl. `secret1234`, és így aktiváljuk a fejlesztői módot csak azoknak a programozóknak, akik egy konkrét IP-címről férnek hozzá, és a sütijükben szerepel az említett token:

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

A fejlesztői/éles/produkciós módot közvetlenül is beállíthatjuk a `Debugger::Development` vagy `Debugger::Production` konstans használatával az `enable()` metódus paramétereként.

.[note]
Ha a Nette Frameworköt használja, nézze meg, hogyan [állítsa be a módot |application:bootstrapping#Fejlesztői vs éles mód] számára, és ez utána a Tracy számára is használva lesz.


Hibanaplózás
============

Éles/produkciós módban a Tracy automatikusan minden hibát és elkapott kivételt egy szöveges naplóba rögzít. Ahhoz, hogy a naplózás működjön, be kell állítanunk a naplózási könyvtár abszolút elérési útját a `$logDirectory` változóba, vagy át kell adnunk az `enable()` metódus második paramétereként:

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

A hibanaplózás rendkívül hasznos. Képzelje el, hogy az alkalmazásának minden felhasználója valójában bétatesztelő, akik ingyen végeznek csúcsmunkát a hibakeresésben, és butaságot követne el, ha értékes jelentéseiket figyelmen kívül hagyva a szemeteskosárba dobná.

Ha saját üzenetet vagy egy Ön által elkapott kivételt kell naplóznunk, használjuk erre a `log()` metódust:

```php
Debugger::log('Váratlan hiba történt'); // szöveges üzenet

try {
	kritikusMuvelet();
} catch (Exception $e) {
	Debugger::log($e); // kivételt is lehet naplózni
	// vagy
	Debugger::log($e, Debugger::ERROR); // e-mail értesítést is küld
}
```

Ha azt szeretné, hogy a Tracy a PHP hibákat, mint az `E_NOTICE` vagy `E_WARNING`, részletes információkkal (HTML jelentés) naplózza, állítsa be a `Debugger::$logSeverity`-t:

```php
Debugger::$logSeverity = E_NOTICE | E_WARNING;
```

Egy igazi profi számára a hibanapló kulcsfontosságú információforrás, és azonnal tájékoztatást szeretne kapni minden új hibáról. A Tracy ebben segítséget nyújt, ugyanis képes e-mailben tájékoztatni a napló új bejegyzéséről. Azt, hogy hova küldje az e-maileket, a `$email` változóval határozzuk meg:

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

Ha a teljes Nette Frameworköt használja, ezt és más beállításokat a [konfigurációs fájlban |nette:configuring] állíthatja be.

Azonban, hogy ne árassza el az e-mail postafiókját, mindig **csak egy üzenetet** küld, és létrehoz egy `email-sent` fájlt. A fejlesztő az e-mail értesítés fogadása után ellenőrzi a naplót, javítja az alkalmazást, és törli a figyelő fájlt, amivel újra aktiválódik az e-mail küldés.


Megnyitás a szerkesztőben
=========================

A hibaoldal megjelenítésekor rá lehet kattintani a fájlnevekre, és azok megnyílnak a szerkesztőben a kurzorral a megfelelő soron. Lehetőség van fájlok létrehozására (`create file` akció) vagy hibák javítására (`fix it` akció) is. Ahhoz, hogy ez működjön, [konfigurálni kell a böngészőt és a rendszert |open-files-in-ide].


Támogatott PHP verziók
======================

| Tracy     | kompatibilis PHP verziókkal
|-----------|-------------------
| 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

Az utolsó patch verzióra érvényes.


Portok
======

Ez a nem hivatalos portok listája más keretrendszerekhez és CMS-ekhez:

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