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\Debugger::enable()' как можно раньше в начале программы, до того, как будет отправлен какой-либо вывод:

```php
use Tracy\Debugger;

require 'vendor/autoload.php'; // альтернатива tracy.phar

Debugger::enable();
```

Первое, что вы заметите на странице, - это панель Tracy Bar в правом нижнем углу. Если вы его не видите, это может означать, что 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; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices
```

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

Примечание: Tracy при активации изменяет уровень сообщения об ошибках на E_ALL. Если вы хотите изменить это значение, сделайте это после вызова `enable()`.


Режим разработки и режим производства .[#toc-development-vs-production-mode]
============================================================================

Как видите, Трейси довольно разговорчив, что можно оценить в среде разработки, в то время как на рабочем сервере это привело бы к катастрофе. Это потому, что там не должна отображаться отладочная информация. Поэтому Tracy имеет **автоопределение среды**, и если пример запущен на рабочем сервере, ошибка будет записана в журнал, а не отображена, и посетитель увидит только удобное сообщение:

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

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

Как работает автоматическое определение режима? Режим является режимом разработки, если приложение работает на localhost (т.е. 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'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}
```

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\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, установите:

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; // display all errors
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // all errors except deprecated notices

Примечание: Tracy при активации изменяет уровень сообщения об ошибках на E_ALL. Если вы хотите изменить это значение, сделайте это после вызова enable().

Режим разработки и режим производства

Как видите, Трейси довольно разговорчив, что можно оценить в среде разработки, в то время как на рабочем сервере это привело бы к катастрофе. Это потому, что там не должна отображаться отладочная информация. Поэтому Tracy имеет автоопределение среды, и если пример запущен на рабочем сервере, ошибка будет записана в журнал, а не отображена, и посетитель увидит только удобное сообщение:

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

Как работает автоматическое определение режима? Режим является режимом разработки, если приложение работает на localhost (т.е. 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'); // text message

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // log exception
	// or
	Debugger::log($e, Debugger::ERROR); // also sends an email notification
}

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: