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 і сині екрани для AJAX-запитів і перенаправлень. Tracy створює власні сесії, зберігає дані у власних тимчасових файлах і використовує файли cookie `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]
==============================================

Скрубер - це фільтр, який запобігає витоку конфіденційних даних з дампа, таких як паролі або облікові дані. Фільтр викликається для кожного елемента дампа масиву або об'єкта і повертає `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()`. Логгер реалізує інтерфейс [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
```


Інтеграція монологу .[#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: інформація [] [] []
Debugger::log('warning', Debugger::WARNING); // пише: [<TIMESTAMP>] main-channel.WARNING: 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 і сині екрани для AJAX-запитів і перенаправлень. Tracy створює власні сесії, зберігає дані у власних тимчасових файлах і використовує файли cookie 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.

Користувацький скрубер

Скрубер – це фільтр, який запобігає витоку конфіденційних даних з дампа, таких як паролі або облікові дані. Фільтр викликається для кожного елемента дампа масиву або об'єкта і повертає 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(). Логгер реалізує інтерфейс 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

Інтеграція монологу

До складу пакета 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: інформація [] [] []
Debugger::log('warning', Debugger::WARNING); // пише: [<TIMESTAMP>] main-channel.WARNING: warning [] []

nginx

Якщо Tracy не працює на nginx, ймовірно, він неправильно налаштований. Якщо є щось на кшталт

try_files $uri $uri/ /index.php;

змініть його на

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