Začenjamo s Tracy

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 ali uporabiti Composer:

composer require tracy/tracy

Lahko si prenesete tudi celoten paket kot datoteko tracy.phar.

Uporaba

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

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.

V Tracy Bar lahko dodate druge koristne panele. Veliko jih najdete v dodatkih ali pa si lahko celo napišete lastne.

Če ne želite prikazovati Tracy Bar, nastavite:

Debugger::$showBar = false;

Vizualizacija napak in izjem

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

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

ali pri neujeti izjemi:

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

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

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.

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

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

Ali pa so lahko prikazane enako kot napake:

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

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:

Produkcijski način zatre prikaz vseh informacij za razhroščevanje, ki jih pošiljate ven s pomočjo dump(), 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():

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:

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

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

Če uporabljate Nette Framework, poglejte, kako nastaviti način zanj, 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():

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

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:

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:

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

Če uporabljate celoten Nette Framework, lahko to in drugo nastavite v konfiguracijski datoteki.

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.

Podprte različice PHP

Velja za zadnjo različico popravka (patch).

Porti

To je seznam neuradnih prenosov za druga ogrodja in CMS:

• Drupal 7
• Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
• OpenCart
• ProcessWire CMS/CMF
• Slim Framework
• Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
• Wordpress