Nette Documentation Preview

syntax 
Інструкції
**********


Content Security Policy
=======================

Якщо ваш веб-сайт використовує 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';");
```


Швидше завантаження
===================

Запуск простий, однак, якщо на вашій веб-сторінці є повільні блокуючі скрипти, вони можуть уповільнити завантаження 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-запитів
=========================

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-запити.


Сховище даних
=============

Tracy може відображати панелі в Tracy Bar та Bluescreen для 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.


Власний скрабер
===============

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


Власний логер
=============

Ми можемо створити власний логер, який буде логувати помилки, неперехоплені винятки, а також буде викликаний методом `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
```


Інтеграція Monolog
------------------

Пакет 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: warning [] []
```


nginx
=====

Якщо Tracy не працює на сервері nginx, ймовірно, він неправильно налаштований. Якщо в конфігурації є щось подібне:

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

змініть це на:

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

Інструкції

Content Security Policy

Якщо ваш веб-сайт використовує Content Security Policy, вам потрібно буде додати ті самі '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 та Bluescreen для 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

Інтеграція Monolog

Пакет 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: warning [] []

nginx

Якщо Tracy не працює на сервері nginx, ймовірно, він неправильно налаштований. Якщо в конфігурації є щось подібне:

try_files $uri $uri/ /index.php;

змініть це на:

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