Започване с Трейси

PHP е идеален език за генериране на фини грешки, тъй като предоставя на програмистите голяма гъвкавост. Поради това Tracy\Debugger е по-ценен. Това е най-добрият инструмент сред диагностичните. Ако срещнете Трейси за първи път, повярвайте ми, животът ви ще се раздели на този преди Трейси и този с нея. Добре дошли в добрата част!

Монтаж и изисквания

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

composer require tracy/tracy

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

Използване на

Активирането на Tracy е много лесно. Просто добавете тези два реда код, за предпочитане непосредствено след зареждането на библиотеката (например require 'vendor/autoload.php') и преди изпращането на изхода към браузъра:

use Tracy\Debugger;

Debugger::enable();

Първото нещо, което ще забележите на сайта, е лентата Tracy.

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

Методът enable() предполага промяна на нивото на съобщението за грешка на E_ALL.

Бар Трейси

Бар “Трейси” е плаващ бар. Той се показва в долния десен ъгъл на страницата. Можете да го преместите с мишката. Той запаметява позицията си след презареждане на страницата.

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

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

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/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\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, грешките и изключенията се показват по съвсем различен начин:

Съобщението за грешка буквално крещи. Можете да видите част от изходния код с подчертания ред, на който е възникнала грешката. В съобщението ясно се обяснява грешката. Целият сайт е интерактивен, опитайте го.

И познайте какво? Фаталните грешки се улавят и показват по същия начин. Не е необходимо да се инсталират разширения (щракнете за пример на живо):

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

Или могат да се показват като грешки:

Debugger::$strictMode = true; // показване на всички грешки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всички грешки, с изключение на известията за изчерпване

За да открием печатните грешки при присвояване на обект, използваме признака Nette\SmartObject.

Производствен режим и регистриране на грешки

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

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

Режимът на извеждане се определя от първия параметър Debugger::enable(). Можете да посочите константа Debugger::Production, или Debugger::Development. Друга възможност е да зададете режим на разработка да се активира, когато приложението е достъпно от определен IP адрес с определена стойност на “бисквитка” tracy-debug. Това се прави с помощта на синтаксиса cookie-value@ip-address.

Ако не е зададена, се използва стойността по подразбиране Debugger::Detect. В този случай системата идентифицира сървъра чрез IP адрес. Производствен режим се избира, ако достъпът до приложението се осъществява чрез публичен IP адрес. Резултатите от локалния IP адрес са в режим на разработка. В повечето случаи не е необходимо да задавате режима. Режимът се разпознава правилно, когато приложението работи на локалния сървър или в производствен режим.

В производствен режим Tracy автоматично записва всички грешки и изключения в текстов дневник. Освен ако не посочите друго, тя ще се съхранява в log/error.log. Този дневник за грешки е изключително полезен. Представете си, че всички потребители на вашето приложение са всъщност бета Tester. Те вършат безплатно най-съвременната работа по откриване на грешки и би било глупаво да изхвърлите дискретно ценните им доклади в кошчето за боклук.

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

Debugger::log('Unexpected error'); // текстово съобщение

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

Директорията за регистриране на грешки може да бъде зададена като втори параметър на метода enable():

Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');

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

Debugger::$logSeverity = E_NOTICE | E_WARNING;

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

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

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

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

Отваряне на файлове в редактора

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

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

Отнася се за най-новите версии на кръпките.

Портове

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