Починаємо з Tracy
*****************

<div class=perex>

Бібліотека Tracy є корисним щоденним помічником для PHP-програміста. Вона допоможе вам:

- швидко виявляти та виправляти помилки
- логувати помилки
- виводити змінні
- вимірювати час виконання скриптів та запитів до бази даних
- відстежувати використання пам'яті

</div>


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

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


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

Найкращий спосіб встановити Tracy — це [завантажити останній пакет |https://github.com/nette/tracy/releases] або використати Composer:

```shell
composer require tracy/tracy
```

Ви також можете завантажити весь пакет як файл [tracy.phar |https://github.com/nette/tracy/releases].


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

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

```php
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.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

До Tracy Bar можна додавати інші корисні панелі. Багато з них можна знайти в [доповненнях |https://componette.org], або ви навіть [можете написати власні |extensions].

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

```php
Debugger::$showBar = false;
```


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

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

/--pre .{font-size: 90%}
<b>Parse error</b>:  syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>
\--

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

/--pre .{font-size: 90%}
<b>Fatal error</b>:  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 <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />
\--

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

[* tracy-exception.webp .{url:-} *]

Повідомлення про помилку буквально кричить. Ми бачимо частину вихідного коду з виділеним рядком, де сталася помилка, а інформація *Call to undefined method Nette\Http\User::isLogedIn()* зрозуміло пояснює, про яку помилку йдеться. Крім того, вся сторінка інтерактивна, ми можемо переходити до більш детальної інформації. [Спробуйте |https://nette.github.io/tracy/tracy-exception.html].

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

[* tracy-error.webp .{url:-} *]

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

[* tracy-notice2.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

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

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

[* tracy-notice.webp .{url:-} *]

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


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

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

[* tracy-error2.webp .{url:-} *]

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

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

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

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

Настійно рекомендуємо поєднувати IP-адресу з cookie. У cookie `tracy-debug` ми зберігаємо секретний токен, наприклад, `secret1234`, і таким чином активуємо режим розробки лише для програмістів, які підключаються з певної IP-адреси та мають зазначений токен у cookie:

```php
Debugger::enable('secret1234@23.75.345.200');
```

Режим розробки/робочий режим можна також встановити безпосередньо, використовуючи константу `Debugger::Development` або `Debugger::Production` як параметр методу `enable()`.

.[note]
Якщо ви використовуєте Nette Framework, подивіться, як [налаштувати режим для нього |application:bootstrapping#Режим розробки проти робочого режиму], і він згодом буде використаний також для Tracy.


Логування помилок
=================

У робочому режимі Tracy автоматично записує всі помилки та перехоплені винятки до текстового логу. Щоб логування могло відбуватися, ми повинні встановити абсолютний шлях до директорії логів у змінну `$logDirectory` або передати його як другий параметр методу `enable()`:

```php
Debugger::$logDirectory = __DIR__ . '/log';
```

Логування помилок при цьому надзвичайно корисне. Уявіть, що всі користувачі вашого застосунку насправді є бета-тестерами, які безкоштовно виконують чудову роботу з пошуку помилок, і ви зробили б дурість, якби викинули їхні цінні звіти непоміченими у смітник.

Якщо нам потрібно залогувати власне повідомлення або перехоплений вами виняток, ми використовуємо для цього метод `log()`:

```php
Debugger::log('Сталася неочікувана помилка'); // текстове повідомлення

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

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

```php
Debugger::$logSeverity = E_NOTICE | E_WARNING;
```

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

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

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

Однак, щоб не заповнювати вашу поштову скриньку, вона завжди надсилає **лише одне повідомлення** і створює файл `email-sent`. Розробник після отримання сповіщення електронною поштою перевіряє лог, виправляє застосунок і видаляє файл моніторингу, чим знову активує надсилання електронних листів.


Відкриття в редакторі
=====================

При відображенні сторінки помилки можна натиснути на імена файлів, і вони відкриються у вашому редакторі з курсором на відповідному рядку. Також можна створювати файли (дія `create file`) або виправляти в них помилки (дія `fix it`). Щоб це працювало, достатньо [налаштувати браузер та систему |open-files-in-ide].


Підтримувані версії PHP
=======================

| Tracy     | сумісний з PHP
|-----------|-------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.4
| Tracy 2.9 | PHP 7.2 – 8.2
| Tracy 2.8 | PHP 7.2 – 8.1
| Tracy 2.6 – 2.7 | PHP 7.1 – 8.0
| Tracy 2.5 | PHP 5.4 – 7.4
| Tracy 2.4 | PHP 5.4 – 7.2

Застосовується до останньої версії патча.


Порти
=====

Це список неофіційних портів для інших фреймворків та CMS:

- [Drupal 7](https://www.drupal.org/project/traced)
- Laravel framework: [recca0120/laravel-tracy](https://github.com/recca0120/laravel-tracy), [whipsterCZ/laravel-tracy](https://github.com/whipsterCZ/laravel-tracy)
- [OpenCart](https://github.com/BurdaPraha/oc_tracy)
- [ProcessWire CMS/CMF](https://github.com/adrianbj/TracyDebugger)
- [Slim Framework](https://github.com/runcmf/runtracy)
- Symfony framework: [kutny/tracy-bundle](https://github.com/kutny/tracy-bundle), [VasekPurchart/Tracy-Blue-Screen-Bundle](https://github.com/VasekPurchart/Tracy-Blue-Screen-Bundle)
- [Wordpress](https://github.com/ktstudio/WP-Tracy)