Začenjamo s Tracy

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

<div class=perex>

Knjižnica Tracy je koristen vsakodnevni pomočnik programerja PHP. Pomagala vam bo:

- hitro odkriti in odpraviti napake

- dnevniško beležiti napake

- izpisovati spremenljivke

- meriti čas izvajanja skript in poizvedb v podatkovni bazi

- spremljati porabo pomnilnika

</div>

PHP je jezik, kot nalašč za ustvarjanje težko odkritih napak, saj daje razvijalcem precejšnjo svobodo. Zato je orodje za razhroščevanje Tracy še toliko bolj dragoceno. Med diagnostičnimi orodji za PHP predstavlja absolutni vrh.

Če se danes prvič srečujete s Tracy, verjemite, da se bo vaše življenje začelo deliti na tisto pred Tracy in tisto z njo. Dobrodošli v boljšem delu!

Namestitev

==========

Najboljši način za namestitev Tracy je [prenesti najnovejši paket |https://github.com/nette/tracy/releases] ali uporabiti Composer:

```shell

composer require tracy/tracy

```

Lahko si prenesete tudi celoten paket kot datoteko [tracy.phar |https://github.com/nette/tracy/releases].

Uporaba

=======

Tracy aktivirate s klicem metode `Tracy\Debugger::enable()` čim prej na začetku programa, pred pošiljanjem kakršnega koli izpisa:

```php

use Tracy\Debugger;

require 'vendor/autoload.php'; // ali `tracy.phar`

Debugger::enable();

```

Prva stvar, ki jo boste opazili na strani, je Tracy Bar v spodnjem desnem kotu. Če ga ne vidite, lahko pomeni, da Tracy teče v produkcijskem načinu. Tracy je namreč iz varnostnih razlogov vidna samo na localhostu. Za testiranje, ali deluje, jo lahko začasno preklopite v razvojni način s parametrom `Debugger::enable(Debugger::Development)`.

Tracy Bar

=========

Tracy Bar je lebdeči panel, ki se prikaže v spodnjem desnem kotu strani. Lahko ga premikate z miško in po ponovnem nalaganju strani si bo zapomnil svoj položaj.

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

V Tracy Bar lahko dodate druge koristne panele. Veliko jih najdete v [dodatkih |https://componette.org] ali pa si lahko celo [napišete lastne |extensions].

Če ne želite prikazovati Tracy Bar, nastavite:

```php

Debugger::$showBar = false;

```

Vizualizacija napak in izjem

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

Zagotovo dobro veste, kako PHP sporoča napake: v izvorno kodo strani izpiše nekaj takega:

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

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

\--

ali pri neujeti izjemi:

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

\--

V takem izpisu se ni ravno lahko znajti. Če vklopite Tracy, se napaka ali izjema prikaže v povsem drugačni obliki:

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

Sporočilo o napaki dobesedno kriči. Vidimo del izvorne kode z označeno vrstico, kjer je prišlo do napake, in informacija *Call to undefined method Nette\\Http\\User::isLogedIn()* razumljivo pojasnjuje, za kakšno napako gre. Celotna stran je poleg tega interaktivna, lahko se preklikate do večjih podrobnosti. [Poskusite |https://nette.github.io/tracy/tracy-exception.html].

In veste kaj? Na ta način ujame in prikaže tudi fatalne napake. Brez potrebe po namestitvi kakršnih koli razširitev.

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

Napake, kot so tipkarske napake v imenu spremenljivke ali poskus odpiranja neobstoječe datoteke, generirajo sporočila ravni `E_NOTICE` ali `E_WARNING`. Te je v grafiki strani lahko spregledati, morda celo sploh niso vidne (razen s pogledom v kodo strani).

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

Ali pa so lahko prikazane enako kot napake:

```php

Debugger::$strictMode = true; // prikaži vse napake

Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // vse napake razen obvestil o zastarelosti

```

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

Opomba: Tracy po aktivaciji spremeni raven poročanja napak na `E_ALL`. Če želite to vrednost spremeniti, to storite po klicu `enable()`.

Razvojni vs. produkcijski način

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

Kot vidite, je Tracy precej zgovorna, kar je cenjeno v razvojnem okolju, medtem ko bi na produkcijskem strežniku povzročilo pravo katastrofo. Tam se namreč ne smejo izpisati nobene informacije za razhroščevanje. Tracy zato razpolaga s **samodejnim zaznavanjem okolja** in če primer zaženete na produkcijskem strežniku, se napaka namesto prikaza zabeleži v dnevnik, obiskovalec pa vidi le uporabniku prijazno sporočilo:

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

Produkcijski način zatre prikaz vseh informacij za razhroščevanje, ki jih pošiljate ven s pomočjo [dump() |dumper], in seveda tudi vseh sporočil o napakah, ki jih generira PHP. Če ste torej v kodi pozabili kakšen `dump($obj)`, vam ni treba skrbeti, na produkcijskem strežniku se ne bo nič izpisalo.

Kako deluje samodejno zaznavanje načina? Način je razvojni, če se aplikacija izvaja na localhostu (tj. IP naslov `127.0.0.1` ali `::1`) in ni prisoten proxy (tj. njegova glava HTTP). Sicer teče v produkcijskem načinu.

Če želite razvojni način omogočiti tudi v drugih primerih, na primer programerjem, ki dostopajo z določenega IP naslova, ga navedite kot parameter metode `enable()`:

```php

Debugger::enable('23.75.345.200'); // lahko navedete tudi polje IP naslovov

```

Vsekakor priporočamo kombiniranje IP naslova s piškotkom. V piškotek `tracy-debug` shranite skrivni žeton, npr. `secret1234`, in na ta način aktivirate razvojni način samo za programerje, ki dostopajo z določenega IP naslova in imajo v piškotku omenjeni žeton:

```php

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

```

Razvojni/produkcijski način lahko neposredno nastavite tudi z uporabo konstant `Debugger::Development` ali `Debugger::Production` kot parametra metode `enable()`.

.[note]

Če uporabljate Nette Framework, poglejte, kako [nastaviti način zanj |application:bootstrapping#Razvojni vs produkcijski način], ki se bo nato uporabil tudi za Tracy.

Dnevniško beleženje napak

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

V produkcijskem načinu Tracy samodejno vse napake in ujete izjeme beleži v besedilni dnevnik. Da lahko dnevniško beleženje poteka, morate nastaviti absolutno pot do imenika za dnevnike v spremenljivko `$logDirectory` ali jo predati kot drugi parameter metode `enable()`:

```php

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

```

Dnevniško beleženje napak je pri tem izjemno koristno. Predstavljajte si, da so vsi uporabniki vaše aplikacije pravzaprav beta testerji, ki brezplačno opravljajo vrhunsko delo pri iskanju napak, in bi naredili neumnost, če bi njihova dragocena poročila brez pozornosti vrgli v koš za smeti.

Če morate zabeležiti lastno sporočilo ali izjemo, ki ste jo ujeli, za to uporabite metodo `log()`:

```php

Debugger::log('Prišlo je do nepričakovane napake'); // besedilno sporočilo

try {

kritickaOperace();

} catch (Exception $e) {

Debugger::log($e); // beležiti je mogoče tudi izjemo

// ali

Debugger::log($e, Debugger::ERROR); // pošlje tudi e-poštno obvestilo

}

```

Če želite, da Tracy beleži napake PHP, kot sta `E_NOTICE` ali `E_WARNING`, s podrobnimi informacijami (poročilo HTML), nastavite `Debugger::$logSeverity`:

```php

Debugger::$logSeverity = E_NOTICE | E_WARNING;

```

Za pravega profesionalca je dnevnik napak ključni vir informacij in želi biti takoj obveščen o vsaki novi napaki. Tracy mu pri tem pomaga, saj zna o novem zapisu v dnevniku obvestiti po e-pošti. Kam pošiljati e-pošto, določite s spremenljivko `$email`:

```php

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

```

Če uporabljate celoten Nette Framework, lahko to in drugo nastavite v [konfiguracijski datoteki |nette:configuring].

Da pa vam ne bi preplavila e-poštnega predala, vedno pošlje **samo eno sporočilo** in ustvari datoteko `email-sent`. Razvijalec po prejemu e-poštnega obvestila preveri dnevnik, popravi aplikacijo in izbriše nadzorno datoteko, s čimer se ponovno aktivira pošiljanje e-pošte.

Odpiranje v urejevalniku

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

Pri prikazu strani z napako lahko kliknete na imena datotek in te se bodo odprle v vašem urejevalniku s kazalcem na ustrezni vrstici. Prav tako lahko datoteke ustvarjate (dejanje `create file`) ali v njih popravljate napake (dejanje `fix it`). Da bi to delovalo, je treba [konfigurirati brskalnik in sistem |open-files-in-ide].

Podprte različice PHP

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

| Tracy | združljiv s 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

Velja za zadnjo različico popravka (patch).

Porti

=====

To je seznam neuradnih prenosov za druga ogrodja in 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)