Nette Documentation Preview

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

<div class=perex>

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

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

</div>


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

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


Встановлення та вимоги .[#toc-installation-and-requirements]
============================================================

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

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

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


Використання .[#toc-usage]
==========================

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

```php
use Tracy\Debugger;

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

Debugger::enable();
```

Перше, що ви помітите на сторінці, це панель Tracy у правому нижньому куті. Якщо ви її не бачите, це може означати, що Tracy працює у виробничому режимі.
Це пов'язано з тим, що з міркувань безпеки Tracy видно лише на localhost. Щоб перевірити, чи працює він, ви можете тимчасово перевести його у режим розробки за допомогою параметра `Debugger::enable(Debugger::Development)`.


Бар Трейсі .[#toc-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;
```


Візуалізація помилок і винятків .[#toc-visualization-of-errors-and-exceptions]
==============================================================================

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

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

or uncaught exception:

/--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/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 <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />
\--

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

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

Повідомлення про помилку буквально кричить. Ви можете побачити частину вихідного коду з виділеним рядком, у якому сталася помилка. Повідомлення чітко пояснює помилку. Весь сайт [інтерактивний, спробуйте його |https://nette.github.io/tracy/tracy-exception.html].

І знаєте що? Фатальні помилки відловлюються і відображаються точно так само. Не потрібно встановлювати жодних розширень (натисніть для живого прикладу):

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

Такі помилки, як помилка в імені змінної або спроба відкрити неіснуючий файл, генерують звіти рівня E_NOTICE або E_WARNING. Їх можна легко пропустити і/або вони можуть бути повністю приховані в графічному макеті веб-сторінки. Дозвольте Tracy керувати ними:

[* 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 виробничий режим .[#toc-development-vs-production-mode]
===================================================================

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

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

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

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

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

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

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

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

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

.[note]
Якщо ви використовуєте Nette Framework, подивіться, як [встановити режим для нього |application:bootstrap#Development vs Production Mode], і він також буде використаний для Tracy.


Журналювання помилок .[#toc-error-logging]
==========================================

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

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

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

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

```php
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`:

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

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

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

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

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


Відкриття файлів у редакторі .[#toc-opening-files-in-the-editor]
================================================================

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


Підтримувані версії PHP .[#toc-supported-php-versions]
======================================================

| Tracy | сумісні з PHP
|-----------|--------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.3
| 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

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


Порти .[#toc-ports]
===================

Це список неофіційних портів на інші фреймворки та 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)

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

Бібліотека Tracy – це корисний помічник для звичайних PHP-програмістів. Вона допоможе вам:

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

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

Tracy сумісні з PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.3
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: