Започване с Трейси
******************

<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, инсталирайте я:

```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>
\--

или неполучено изключение:

/--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-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()`.


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

Както можете да видите, Трейси е доста разговорлив, което може да се оцени в среда за разработка, докато на производствен сървър това би довело до катастрофа. Това е така, защото там не трябва да се показва информация за отстраняване на грешки. Поради това 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 адреса с бисквитка. Съхранявайте таен токен, например `secret1234`, в бисквитката `tracy-debug` и по този начин активирайте режима за разработка само за разработчици, осъществяващи достъп от определен IP адрес, които имат споменатия токен в бисквитката:

```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); // също така изпраща уведомление по имейл
}
```

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].

За да предпази пощенската ви кутия от препълване, Трейси изпраща **само едно съобщение** и създава файл `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
| 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

Отнася се за най-новите версии на кръпките.


Портове .[#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)