Nette Documentation Preview

syntax 
Рецепти
*******


Политика за сигурност на съдържанието .[#toc-content-security-policy]
=====================================================================

Ако сайтът ви използва политика за сигурност на съдържанието, ще трябва да добавите `'nonce-<value>'` и `'strict-dynamic'` към `script-src`, за да може Tracy да работи правилно. Някои приставки на трети страни може да изискват допълнителни директиви.
Nonce не се поддържа в директивата `style-src`, ако използвате тази директива, трябва да добавите `'unsafe-inline'`, но това трябва да се избягва в производствен режим.

Пример за конфигурация за [Nette Framework |nette:configuring]:

```neon
http:
	csp:
		script-src: [nonce, strict-dynamic]
```

Пример в чист PHP:

```php
$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");
```


По-бързо зареждане .[#toc-faster-loading]
=========================================

Основната интеграция е проста, но ако имате бавно блокиращи скриптове в уеб страницата, те могат да забавят зареждането на Tracy.
Решението е да поставите `<?php Tracy\Debugger::renderLoader() ?>` в шаблона си преди всички скриптове:

```latte
<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
</head>
```


Отстраняване на грешки при заявките AJAX .[#toc-debugging-ajax-requests]
========================================================================

Tracy автоматично улавя заявките AJAX, направени с помощта на jQuery или родния API на `fetch`. Тези заявки се показват като допълнителни редове в лентата Tracy, което позволява лесно и удобно отстраняване на грешки в AJAX.

Ако не искате да улавяте автоматично AJAX заявки, можете да деактивирате тази функция, като зададете JavaScript променливата:

```js
window.TracyAutoRefresh = false;
```

За ръчно следене на конкретни AJAX заявки добавете HTTP заглавието `X-Tracy-Ajax` със стойността, върната от `Tracy.getAjaxHeader()`. Ето пример за използването му с функцията `fetch`:

```js
fetch(url, {
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'X-Tracy-Ajax': Tracy.getAjaxHeader(),
    }
})
```

Този подход позволява селективно отстраняване на грешки в AJAX заявките.


Съхранение на данни .[#toc-data-storage]
========================================

Tracy може да показва панели Tracy bar и Bluescreens за AJAX заявки и пренасочвания. Tracy създава свои собствени сесии, съхранява данни в свои собствени временни файлове и използва бисквитка `tracy-session`.

Tracy може също така да бъде конфигуриран да използва собствена PHP сесия, която се стартира преди Tracy да бъде включен:

```php
session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();
```

В случай че стартирането на сесия изисква по-сложна инициализация, можете да стартирате Tracy веднага (така че да може да се справи с всички възникнали грешки) и след това да инициализирате обработчика на сесията и накрая да информирате Tracy, че сесията е готова за използване, като използвате функцията `dispatch()`:

```php
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// последвано от инициализиране на сесията
// и стартиране на сесията
session_start();

Debugger::dispatch();
```

Функцията `setSessionStorage()` съществува от версия 2.9 насам, като преди това Tracy винаги е използвал родната PHP сесия.


Потребителски скрубер .[#toc-custom-scrubber]
=============================================

Scrubber е филтър, който предотвратява изтичането на чувствителни данни от дъмповете, като например пароли или пълномощни. Филтърът се извиква за всеки елемент от изхвърления масив или обект и връща `true`, ако стойността е чувствителна. В този случай вместо стойността се извежда `*****`.

```php
// избягва изхвърлянето на стойности на ключове и свойства като `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD` и др.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// използваме го за всички дъмпове в BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Потребителски регистратор .[#toc-custom-logger]
===============================================

Можем да създадем потребителски регистратор, който да регистрира грешки, незасегнати изключения, а също и да бъде извикан от `Tracy\Debugger::log()`. Logger имплементира интерфейса [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// изпраща заявка до Slack
	}
}
```

И след това го активираме:

```php
Tracy\Debugger::setLogger(new SlackLogger);
```

Ако използваме пълната Nette Framework, можем да я зададем в конфигурационния файл на NEON:

```neon
services:
	tracy.logger: SlackLogger
```


Monolog Integration .[#toc-monolog-integration]
-----------------------------------------------

Пакетът Tracy предоставя PSR-3 адаптер, който позволява интегрирането на [monolog/monolog](https://github.com/Seldaek/monolog).

```php
$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // пише: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // записва: [<TIMESTAMP>] main-channel.WARNING: предупреждение [] []
```


nginx .[#toc-nginx]
===================

Ако Tracy не работи на nginx, вероятно е неправилно конфигуриран. Ако има нещо като

```nginx
try_files $uri $uri/ /index.php;
```

да го промените на

```nginx
try_files $uri $uri/ /index.php$is_args$args;
```

Рецепти

Политика за сигурност на съдържанието

Ако сайтът ви използва политика за сигурност на съдържанието, ще трябва да добавите 'nonce-<value>' и 'strict-dynamic' към script-src, за да може Tracy да работи правилно. Някои приставки на трети страни може да изискват допълнителни директиви. Nonce не се поддържа в директивата style-src, ако използвате тази директива, трябва да добавите 'unsafe-inline', но това трябва да се избягва в производствен режим.

Пример за конфигурация за Nette Framework:

http:
	csp:
		script-src: [nonce, strict-dynamic]

Пример в чист PHP:

$nonce = base64_encode(random_bytes(20));
header("Content-Security-Policy: script-src 'nonce-$nonce' 'strict-dynamic';");

По-бързо зареждане

Основната интеграция е проста, но ако имате бавно блокиращи скриптове в уеб страницата, те могат да забавят зареждането на Tracy. Решението е да поставите <?php Tracy\Debugger::renderLoader() ?> в шаблона си преди всички скриптове:

<!DOCTYPE html>
<html>
<head>
	<title>...<title>
	<?php Tracy\Debugger::renderLoader() ?>
	<link rel="stylesheet" href="assets/style.css">
	<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
</head>

Отстраняване на грешки при заявките AJAX

Tracy автоматично улавя заявките AJAX, направени с помощта на jQuery или родния API на fetch. Тези заявки се показват като допълнителни редове в лентата Tracy, което позволява лесно и удобно отстраняване на грешки в AJAX.

Ако не искате да улавяте автоматично AJAX заявки, можете да деактивирате тази функция, като зададете JavaScript променливата:

window.TracyAutoRefresh = false;

За ръчно следене на конкретни AJAX заявки добавете HTTP заглавието X-Tracy-Ajax със стойността, върната от Tracy.getAjaxHeader(). Ето пример за използването му с функцията fetch:

fetch(url, {
    headers: {
        'X-Requested-With': 'XMLHttpRequest',
        'X-Tracy-Ajax': Tracy.getAjaxHeader(),
    }
})

Този подход позволява селективно отстраняване на грешки в AJAX заявките.

Съхранение на данни

Tracy може да показва панели Tracy bar и Bluescreens за AJAX заявки и пренасочвания. Tracy създава свои собствени сесии, съхранява данни в свои собствени временни файлове и използва бисквитка tracy-session.

Tracy може също така да бъде конфигуриран да използва собствена PHP сесия, която се стартира преди Tracy да бъде включен:

session_start();
Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

В случай че стартирането на сесия изисква по-сложна инициализация, можете да стартирате Tracy веднага (така че да може да се справи с всички възникнали грешки) и след това да инициализирате обработчика на сесията и накрая да информирате Tracy, че сесията е готова за използване, като използвате функцията dispatch():

Debugger::setSessionStorage(new Tracy\NativeSession);
Debugger::enable();

// последвано от инициализиране на сесията
// и стартиране на сесията
session_start();

Debugger::dispatch();

Функцията setSessionStorage() съществува от версия 2.9 насам, като преди това Tracy винаги е използвал родната PHP сесия.

Потребителски скрубер

Scrubber е филтър, който предотвратява изтичането на чувствителни данни от дъмповете, като например пароли или пълномощни. Филтърът се извиква за всеки елемент от изхвърления масив или обект и връща true, ако стойността е чувствителна. В този случай вместо стойността се извежда *****.

// избягва изхвърлянето на стойности на ключове и свойства като `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD` и др.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// използваме го за всички дъмпове в BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Потребителски регистратор

Можем да създадем потребителски регистратор, който да регистрира грешки, незасегнати изключения, а също и да бъде извикан от Tracy\Debugger::log(). Logger имплементира интерфейса Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// изпраща заявка до Slack
	}
}

И след това го активираме:

Tracy\Debugger::setLogger(new SlackLogger);

Ако използваме пълната Nette Framework, можем да я зададем в конфигурационния файл на NEON:

services:
	tracy.logger: SlackLogger

Monolog Integration

Пакетът Tracy предоставя PSR-3 адаптер, който позволява интегрирането на monolog/monolog.

$monolog = new Monolog\Logger('main-channel');
$monolog->pushHandler(new Monolog\Handler\StreamHandler($logFilePath, Monolog\Logger::DEBUG));

$tracyLogger = new Tracy\Bridges\Psr\PsrToTracyLoggerAdapter($monolog);
Debugger::setLogger($tracyLogger);
Debugger::enable();

Debugger::log('info'); // пише: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // записва: [<TIMESTAMP>] main-channel.WARNING: предупреждение [] []

nginx

Ако Tracy не работи на nginx, вероятно е неправилно конфигуриран. Ако има нещо като

try_files $uri $uri/ /index.php;

да го промените на

try_files $uri $uri/ /index.php$is_args$args;