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

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 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/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. Их можно легко пропустить и/или они могут быть полностью скрыты в графическом макете веб-страницы. Позвольте Tracy управлять ими:

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

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

Для того чтобы обнаружить опечатки при присвоении объекту, мы используем признак 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. Этот журнал ошибок чрезвычайно полезен. Представьте себе, что все пользователи вашего приложения на самом деле являются бетатестерами. Они бесплатно выполняют передовую работу по поиску ошибок, и было бы глупо, если бы вы незаметно выбросили их ценные отчеты в корзину.

Если вам нужно записать в журнал собственные сообщения или пойманные исключения, используйте метод 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
}

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

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