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

PHP – ідеальна мова для створення ледь помітних помилок, тому що вона надає програмістам велику гнучкість. Tracy\Debugger більш цінний через це. Це найкращий інструмент серед діагностичних.

Якщо ви зустрічаєтеся з Трейсі вперше, повірте, ваше життя почне ділитися на те, що було до Трейсі, і те, що з нею. Ласкаво просимо в хорошу частину!

Встановлення та вимоги

Найкращий спосіб встановлення Tracy – завантажити останній пакет або використовувати Composer:

composer require tracy/tracy

Також ви можете завантажити весь пакет або файл tracy.phar.

Використання

Tracy активується викликом методу `Tracy\Debugger::enable()' якнайшвидше на початку програми, до того, як буде надіслано будь-який вивід:

use Tracy\Debugger;

require 'vendor/autoload.php'; // або tracy.phar

Debugger::enable();

Перше, що ви помітите на сторінці, це панель Tracy у правому нижньому куті. Якщо ви її не бачите, це може означати, що 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; // виводити усі помилки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всі помилки, крім застарілих повідомлень

Зауваження: Tracy при активації змінює рівень повідомлення про помилки на E_ALL. Якщо ви хочете змінити це, зробіть це, звернувшись за адресою enable().

Розвиток vs виробничий режим

Як бачите, Трейсі досить балакучий, що можна оцінити в середовищі розробки, в той час як на продакшн-сервері це призвело б до катастрофи. Це тому, що там не повинна відображатися ніяка налагоджувальна інформація. Тому Tracy має автовизначення оточення, і якщо приклад виконується на реальному сервері, помилка буде записана в журнал, а не показана, і відвідувач побачить лише зручне для користувача повідомлення:

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

Як працює автоматичне визначення режиму? Режим є режимом розробки, якщо додаток працює на локальному хості (тобто 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'); // текстове повідомлення

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

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