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

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

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

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

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

composer require tracy/tracy

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

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

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

use Tracy\Debugger;

require 'vendor/autoload.php'; // алтернативно tracy.phar

Debugger::enable();

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

Бар Трейси

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

Можете да добавите други полезни панели към лентата 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; // всички грешки, с изключение на известията за изчерпване

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

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

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

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

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

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

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

Определено препоръчваме да комбинирате IP адреса с бисквитка. Съхранявайте таен токен, например secret1234, в бисквитката tracy-debug и по този начин активирайте режима за разработка само за разработчици, осъществяващи достъп от определен 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('Unexpected error'); // текстово съобщение

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

If you want Tracy to log PHP errors like E_NOTICE or E_WARNING with detailed information (HTML report), set 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