Nette Documentation Preview

syntax 
Първи стъпки с 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; // всички грешки освен известията за отхвърляне (deprecated)
```

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

Забележка: След активиране Tracy променя нивото на докладване на грешки на E_ALL. Ако искате да промените тази стойност, направете го след извикването на `enable()`.


Режим на разработка срещу продукционен режим
============================================

Както виждате, 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). В бисквитката `tracy-debug` съхраняваме таен токен, напр. `secret1234`, и по този начин активираме режима за разработка само за програмисти, достъпващи от конкретен IP адрес, които имат споменатия токен в бисквитката:

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

Важи за последната пач версия.


Портове
=======

Това е списък с неофициални портове за други framework-ове и 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

Библиотеката Tracy е полезен ежедневен помощник на PHP програмиста. Ще ви помогне да:

  • бързо откривате и коригирате грешки
  • логвате грешки
  • извеждате променливи
  • измервате времето на скриптове и заявки към базата данни
  • следите изискванията за памет

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; // всички грешки освен известията за отхвърляне (deprecated)

Забележка: След активиране Tracy променя нивото на докладване на грешки на E_ALL. Ако искате да промените тази стойност, направете го след извикването на enable().

Режим на разработка срещу продукционен режим

Както виждате, 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). В бисквитката tracy-debug съхраняваме таен токен, напр. secret1234, и по този начин активираме режима за разработка само за програмисти, достъпващи от конкретен IP адрес, които имат споменатия токен в бисквитката:

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('Възникна неочаквана грешка'); // текстово съобщение

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

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

Важи за последната пач версия.

Портове

Това е списък с неофициални портове за други framework-ове и CMS: