Починаємо з Tracy

PHP — це мова, яка ніби створена для створення важко виявлюваних помилок, оскільки надає розробникам значну свободу. Тим ціннішим є інструмент налагодження Tracy. Серед діагностичних інструментів для PHP він є абсолютним лідером.

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

Встановлення

Найкращий спосіб встановити Tracy — це завантажити останній пакет або використати Composer:

composer require tracy/tracy

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

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

Tracy активується викликом методу 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 — це плаваюча панель, яка з'являється в правому нижньому куті сторінки. Її можна переміщати мишею, і після перезавантаження сторінки вона запам'ятає свою позицію.

До Tracy Bar можна додавати інші корисні панелі. Багато з них можна знайти в доповненнях, або ви навіть можете написати власні.

Якщо ви не хочете відображати Tracy Bar, встановіть:

Debugger::$showBar = false;

Візуалізація помилок та винятків

Ви, напевно, добре знаєте, як PHP повідомляє про помилки: у вихідний код сторінки виводиться щось подібне:

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

або при неперехопленому винятку:

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

Повідомлення про помилку буквально кричить. Ми бачимо частину вихідного коду з виділеним рядком, де сталася помилка, а інформація Call to undefined method Nette\Http\User::isLogedIn() зрозуміло пояснює, про яку помилку йдеться. Крім того, вся сторінка інтерактивна, ми можемо переходити до більш детальної інформації. Спробуйте.

І знаєте що? Таким чином вона перехоплює і відображає навіть фатальні помилки. Без необхідності встановлювати будь-які розширення.

Помилки, такі як одруківка в назві змінної або спроба відкрити неіснуючий файл, генерують повідомлення рівня E_NOTICE або E_WARNING. Їх легко пропустити в графіці сторінки, вони навіть можуть бути зовсім невидимими (хіба що при перегляді коду сторінки).

Або вони можуть відображатися так само, як помилки:

Debugger::$strictMode = true; // показати всі помилки
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // всі помилки, крім повідомлень про застарілість

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

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

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

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

Як працює автоматичне визначення режиму? Режим є режимом розробки, якщо застосунок запущено на localhost (тобто IP-адреса 127.0.0.1 або ::1) і немає проксі (тобто його HTTP-заголовка). В іншому випадку він працює в робочому режимі.

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

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

Настійно рекомендуємо поєднувати IP-адресу з cookie. У cookie tracy-debug ми зберігаємо секретний токен, наприклад, secret1234, і таким чином активуємо режим розробки лише для програмістів, які підключаються з певної 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('Doslo k necekane chybe'); // текстове повідомлення

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

Якщо ви хочете, щоб Tracy логувала помилки PHP, такі як E_NOTICE або E_WARNING, з детальною інформацією (HTML-звіт), встановіть Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Для справжнього професіонала лог помилок є ключовим джерелом інформації, і він хоче бути негайно поінформованим про кожну нову помилку. Tracy йде йому назустріч, оскільки вміє інформувати про новий запис у лозі електронною поштою. Куди надсилати листи, визначаємо змінною $email:

Debugger::$email = 'admin@example.com';

Якщо ви використовуєте весь Nette Framework, це та інші налаштування можна встановити в конфігураційному файлі.

Однак, щоб не заповнювати вашу поштову скриньку, вона завжди надсилає лише одне повідомлення і створює файл 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