Начало работы с Трейси
Библиотека Tracy – это полезный помощник для обычных PHP-программистов. Она поможет вам:
- быстро обнаруживать и исправлять ошибки
- регистрировать ошибки
- дамп переменных
- измерять время выполнения скриптов/запросов
- просматривать потребление памяти
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
Tracy | совместимые с PHP |
---|---|
Tracy 2.10 – 3.0 | PHP 8.0 – 8.2 |
Tracy 2.9 | PHP 7.2 – 8.2 |
Tracy 2.8 | PHP 7.2 – 8.1 |
Трейси 2.6 – 2.7 | PHP 7.1 – 8.0 |
Трейси 2.5 | PHP 5.4 – 7.4 |
Трейси 2.4 | PHP 5.4 – 7.2 |
Применимо к последним версиям патчей.
Порты
Это список неофициальных портов на другие фреймворки и 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