Начинаем работать с 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 работает в production-режиме. 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; // все ошибки, кроме уведомлений о deprecation

Примечание: Tracy после активации изменяет уровень сообщений об ошибках на E_ALL. Если вы хотите изменить это значение, сделайте это после вызова enable().

Режим разработки vs production-режим

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

Production-режим подавляет отображение всей отладочной информации, которую мы отправляем наружу с помощью dump(), и, конечно же, всех сообщений об ошибках, которые генерирует PHP. Так что если вы забыли в коде какой-нибудь dump($obj), можете не беспокоиться, на production-сервере ничего не выведется.

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

Если мы хотим разрешить режим разработки и в других случаях, например, программистам, обращающимся с определенного IP-адреса, мы укажем его как параметр метода enable():

Debugger::enable('23.75.345.200'); // можно также указать массив IP-адресов

Настоятельно рекомендуем комбинировать IP-адрес с cookie. В cookie tracy-debug сохраним секретный токен, напр. secret1234, и таким образом активируем режим разработки только для программистов, обращающихся с определенного IP-адреса, у которых в cookie есть упомянутый токен:

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

Режим разработки/production-режим мы также можем установить напрямую использованием константы Debugger::Development или Debugger::Production в качестве параметра метода enable().

Если вы используете Nette Framework, посмотрите, как установить режим для него, и он затем будет использован и для Tracy.

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

В production-режиме Tracy автоматически все ошибки и перехваченные исключения записывает в текстовый лог. Чтобы логирование могло происходить, мы должны установить абсолютный путь к каталогу логов в переменную $logDirectory или передать как второй параметр метода enable():

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

Логирование ошибок при этом чрезвычайно полезно. Представьте себе, что все пользователи вашего приложения на самом деле являются бета-тестерами, которые бесплатно выполняют первоклассную работу по поиску ошибок, и вы бы совершили глупость, если бы выбросили их ценные отчеты без внимания в мусорную корзину.

Если нам нужно залогировать собственное сообщение или перехваченное вами исключение, мы используем для этого метод log():

Debugger::log('Произошла неожиданная ошибка'); // текстовое сообщение

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

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

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Для настоящего профессионала лог ошибок является ключевым источником информации, и он хочет быть немедленно проинформирован о каждой новой ошибке. Tracy идет ему в этом навстречу, она ведь умеет информировать по e-mail о новой записи в логе. Куда отправлять e-mail, мы определяем переменной $email:

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

Если вы используете весь Nette Framework, это и другое можно настроить в конфигурационном файле.

Однако, чтобы она не завалила ваш почтовый ящик, она всегда отправляет только одно сообщение и создает файл email-sent. Разработчик после получения уведомления по e-mail проверяет лог, исправляет приложение и удаляет файл мониторинга, тем самым снова активируется отправка e-mail.

Открытие в редакторе

При отображении страницы ошибки можно кликнуть на имена файлов, и они откроются в вашем редакторе с курсором на соответствующей строке. Также можно создавать файлы (действие 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