Початок роботи з Трейсі

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; // виводити усі помилки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всі помилки, крім застарілих повідомлень

Для того щоб виявити помилки під час присвоєння об'єкту, ми використовуємо ознаку 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'); // текстове повідомлення

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // занести виключення в лог
	// або
	Debugger::log($e, Debugger::ERROR); // також відправляє повідомлення на email
}

Каталог для протоколювання помилок можна задати другим параметром методу 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