Начало работы с Трейси

PHP – идеальный язык для создания едва различимых ошибок, потому что он предоставляет программистам большую гибкость. Tracy\Debugger более ценен из-за этого. Это лучший инструмент среди диагностических.

Если вы встречаетесь с Трейси впервые, поверьте, ваша жизнь начнет делиться на ту, что была до Трейси, и ту, что с ней. Добро пожаловать в хорошую часть!

Установка и требования

Лучший способ установки Tracy – скачать последний пакет или использовать Composer:

composer require tracy/tracy

Также вы можете скачать весь пакет или файл tracy.phar.

Использование

Трейси активируется вызовом метода `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, установите:

Debugger::$showBar = false;

Визуализация ошибок и исключений

Наверняка вы знаете, как PHP сообщает об ошибках: в исходном коде страницы есть что-то вроде этого:

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

or uncaught exception:

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

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

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

Такие ошибки, как опечатка в имени переменной или попытка открыть несуществующий файл, генерируют отчеты уровня E_NOTICE или E_WARNING. Их можно легко пропустить и/или они могут быть полностью скрыты в графическом макете веб-страницы. Позвольте Tracy управлять ими:

Или они могут отображаться как ошибки:

Debugger::$strictMode = true; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices

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

Режим разработки и режим производства

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

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

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

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

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

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

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'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}

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, вы можете установить эту и другие переменные в конфигурационном файле.

Чтобы защитить свой почтовый ящик от переполнения, Tracy отправляет только одно сообщение и создает файл 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