Първи стъпки с Tracy

PHP е език, създаден за допускане на трудно откриваеми грешки, тъй като дава на разработчиците значителна свобода. Толкова по-ценен е инструментът за дебъгване Tracy. Сред диагностичните инструменти за PHP той представлява абсолютния връх.

Ако днес се срещате с Tracy за първи път, повярвайте, че животът ви ще започне да се дели на този преди Tracy и този с нея. Добре дошли в по-добрата част!

Инсталация

Най-добрият начин да инсталирате Tracy е да изтеглите най-новия пакет или да използвате Composer:

composer require tracy/tracy

Можете също да изтеглите целия пакет като файл tracy.phar.

Използване

Активираме Tracy чрез извикване на метода Tracy\Debugger::enable() възможно най-рано в началото на програмата, преди изпращането на какъвто и да е изход:

use Tracy\Debugger;

require 'vendor/autoload.php'; // или tracy.phar

Debugger::enable();

Първото нещо, което ще забележите на страницата, е Tracy Bar в долния десен ъгъл. Ако не го виждате, това може да означава, че Tracy работи в продукционен режим. От съображения за сигурност Tracy е видима само на localhost. За да тествате дали работи, можете временно да я превключите в режим на разработка с помощта на параметъра Debugger::enable(Debugger::Development).

Tracy Bar

Tracy Bar е плаващ панел, който се показва в долния десен ъгъл на страницата. Можем да го преместваме с мишката и след презареждане на страницата той ще запомни позицията си.

Към Tracy Bar могат да се добавят други полезни панели. Много от тях можете да намерите в добавките или дори можете да напишете свои собствени.

Ако не искате да показвате Tracy Bar, задайте:

Debugger::$showBar = false;

Визуализация на грешки и изключения

Със сигурност знаете добре как PHP съобщава за грешки: в изходния код на страницата извежда нещо такова:

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

или при неприхванато изключение:

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

Ориентирането в такъв изход не е никак лесно. Ако включим Tracy, грешката или изключението ще се покажат в съвсем различна форма:

Съобщението за грешка буквално крещи. Виждаме част от изходния код с подчертан ред, където е възникнала грешката, а информацията Call to undefined method Nette\Http\User::isLogedIn() ясно обяснява каква е грешката. Освен това цялата страница е интерактивна, можем да кликваме за повече подробности. Опитайте.

И знаете ли какво? По този начин се прихващат и показват дори фатални грешки. Без необходимост от инсталиране на каквито и да било разширения.

Грешки като печатна грешка в името на променлива или опит за отваряне на несъществуващ файл генерират съобщения от ниво E_NOTICE или E_WARNING. Те лесно могат да бъдат пропуснати в графиката на страницата, дори може изобщо да не са видими (освен ако не погледнете кода на страницата).

Или могат да бъдат показани по същия начин като грешките:

Debugger::$strictMode = true; // покажи всички грешки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всички грешки освен известията за отхвърляне (deprecated)

Забележка: След активиране Tracy променя нивото на докладване на грешки на E_ALL. Ако искате да промените тази стойност, направете го след извикването на enable().

Режим на разработка срещу продукционен режим

Както виждате, Tracy е доста „приказлива“, което може да се оцени в среда за разработка, докато на продукционен сървър това би причинило истинско бедствие. Там не трябва да се извежда никаква информация за дебъгване. Затова Tracy разполага с автоматично откриване на средата и ако стартираме примера на реален сървър, грешката ще бъде логната вместо показана, а посетителят ще види само разбираемо за потребителя съобщение:

Продукционният режим потиска показването на цялата информация за дебъгване, която изпращаме навън с помощта на dump(), и разбира се, всички съобщения за грешки, генерирани от PHP. Така че, ако сте забравили някое dump($obj) в кода, не се притеснявайте, нищо няма да се изведе на продукционния сървър.

Как работи автоматичното откриване на режима? Режимът е за разработка, ако приложението се изпълнява на localhost (т.е. IP адрес 127.0.0.1 или ::1) и няма налично прокси (т.е. негов HTTP хедър). В противен случай работи в продукционен режим.

Ако искаме да разрешим режима за разработка и в други случаи, например за програмисти, достъпващи от конкретен IP адрес, го посочваме като параметър на метода enable():

Debugger::enable('23.75.345.200'); // може да се посочи и масив от IP адреси

Определено препоръчваме да комбинирате IP адреса с бисквитка (cookie). В бисквитката tracy-debug съхраняваме таен токен, напр. secret1234, и по този начин активираме режима за разработка само за програмисти, достъпващи от конкретен IP адрес, които имат споменатия токен в бисквитката:

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

Можем също така директно да зададем режима за разработка/продукционен режим, като използваме константата Debugger::Development или Debugger::Production като параметър на метода enable().

Ако използвате Nette Framework, вижте как да зададете режима за него и той впоследствие ще се използва и за Tracy.

Логване на грешки

В продукционен режим Tracy автоматично записва всички грешки и прихванати изключения в текстов лог. За да може логването да се осъществява, трябва да зададем абсолютния път до директорията за логване в променливата $logDirectory или да го предадем като втори параметър на метода enable():

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

Логването на грешки е изключително полезно. Представете си, че всички потребители на вашето приложение всъщност са бета тестери, които безплатно вършат отлична работа в намирането на грешки и бихте направили глупост, ако изхвърлите техните ценни доклади в кошчето за боклук, без да им обърнете внимание.

Ако трябва да логнем собствено съобщение или прихванато от нас изключение, използваме за това метода log():

Debugger::log('Възникна неочаквана грешка'); // текстово съобщение

try {
	kritickaOperace();
} catch (Exception $e) {
	Debugger::log($e); // може да се логва и изключение
	// или
	Debugger::log($e, Debugger::ERROR); // изпраща и известие по имейл
}

Ако искате Tracy да логва PHP грешки като E_NOTICE или E_WARNING с подробна информация (HTML отчет), задайте Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

За истинския професионалист логът на грешките е ключов източник на информация и той иска да бъде незабавно информиран за всяка нова грешка. Tracy му помага в това, тъй като може да информира за нов запис в лога по имейл. Къде да се изпращат имейлите, определяме с променливата $email:

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

Ако използвате целия Nette Framework, това и други настройки могат да бъдат зададени в конфигурационния файл.

За да не препълни обаче имейл кутията ви, тя винаги изпраща само едно съобщение и създава файл email-sent. След получаване на известието по имейл, разработчикът проверява лога, коригира приложението и изтрива файла за наблюдение, с което отново се активира изпращането на имейли.

Отваряне в редактор

При показване на страницата с грешка можете да кликнете върху имената на файловете и те ще се отворят във вашия редактор с курсора на съответния ред. Също така можете да създавате файлове (действие create file) или да коригирате грешки в тях (действие fix it). За да работи това, е достатъчно да конфигурирате браузъра и системата.

Поддържани версии на PHP

Важи за последната пач версия.

Портове

Това е списък с неофициални портове за други framework-ове и 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