Nette Documentation Preview

syntax 
Przepisy
********


Polityka bezpieczeństwa treści .[#toc-content-security-policy]
==============================================================

Jeśli Twoja witryna korzysta z Content Security Policy, będziesz musiał dodać `'nonce-<value>'` i `'strict-dynamic'` do `script-src`, aby Tracy działała poprawnie. Niektóre wtyczki 3rd mogą wymagać dodatkowych dyrektyw.
Nonce nie jest obsługiwany w dyrektywie `style-src`, jeśli używasz tej dyrektywy, musisz dodać `'unsafe-inline'`, ale należy tego unikać w trybie produkcyjnym.

Przykład konfiguracji dla [Nette Framework |nette:configuring]:

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

Przykład w czystym PHP:

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


Szybsze ładowanie .[#toc-faster-loading]
========================================

Podstawowa integracja jest prosta, jednak jeśli posiadasz wolno blokujące się skrypty na stronie, mogą one spowolnić ładowanie Tracy.
Rozwiązaniem jest umieszczenie `<?php Tracy\Debugger::renderLoader() ?>` w swoim szablonie przed jakimikolwiek skryptami:

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


Debugowanie żądań AJAX .[#toc-debugging-ajax-requests]
======================================================

Tracy automatycznie przechwytuje żądania AJAX wykonane przy użyciu jQuery lub natywnego interfejsu API `fetch`. Żądania te są wyświetlane jako dodatkowe wiersze na pasku Tracy, umożliwiając łatwe i wygodne debugowanie AJAX.

Jeśli nie chcesz automatycznie przechwytywać żądań AJAX, możesz wyłączyć tę funkcję, ustawiając zmienną JavaScript:

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

W celu ręcznego monitorowania określonych żądań AJAX, dodaj nagłówek HTTP `X-Tracy-Ajax` z wartością zwracaną przez `Tracy.getAjaxHeader()`. Oto przykład użycia go z funkcją `fetch`:

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

Takie podejście pozwala na selektywne debugowanie żądań AJAX.


Przechowywanie danych .[#toc-data-storage]
==========================================

Tracy może wyświetlać panele paska Tracy i ekrany Bluescreens dla żądań AJAX i przekierowań. Tracy tworzy własne sesje, przechowuje dane we własnych plikach tymczasowych i używa pliku cookie `tracy-session`.

Tracy może być również skonfigurowany do korzystania z natywnej sesji PHP, która jest uruchamiana przed włączeniem Tracy:

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

W przypadku, gdy uruchomienie sesji wymaga bardziej złożonej inicjalizacji, można od razu uruchomić Tracy (aby mogła obsłużyć wszelkie pojawiające się błędy), a następnie zainicjować obsługę sesji i ostatecznie poinformować Tracy, że sesja jest gotowa do użycia za pomocą funkcji `dispatch()`:

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

// po czym następuje inicjalizacja sesji
// i rozpocząć sesję
session_start();

Debugger::dispatch();
```

Funkcja `setSessionStorage()` istnieje od wersji 2.9, wcześniej Tracy zawsze używała natywnej sesji PHP.


Custom Scrubber .[#toc-custom-scrubber]
=======================================

Scrubber jest filtrem, który zapobiega wyciekowi wrażliwych danych z zrzutów, takich jak hasła lub poświadczenia. Filtr ten jest wywoływany dla każdego elementu zrzucanej tablicy lub obiektu i zwraca `true`, jeśli wartość jest wrażliwa. W takim przypadku zamiast wartości wypisywana jest `*****`.

```php
// pozwala uniknąć dumpingu wartości kluczy i właściwości takich jak `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, itp.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// używamy go do wszystkich zrzutów wewnątrz BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Logger niestandardowy .[#toc-custom-logger]
===========================================

Możemy stworzyć własny logger, który będzie rejestrował błędy, niezałatwione wyjątki, a także będzie wywoływany przez `Tracy\Debugger::log()`. Logger implementuje interfejs [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// wysyła zapytanie do Slacka
	}
}
```

A następnie aktywujemy go:

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

Jeśli korzystamy z pełnego Nette Framework, możemy go ustawić w pliku konfiguracyjnym NEON:

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


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

Pakiet Tracy dostarcza adapter PSR-3, pozwalający na integrację [monologu/monologu](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'); // pisze: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // pisze: [<TIMESTAMP>] main-channel.WARNING: warning [] []
```


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

Jeśli Tracy nie działa na nginx, prawdopodobnie jest źle skonfigurowany. Jeśli jest coś takiego jak

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

zmień to na

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

Przepisy

Polityka bezpieczeństwa treści

Jeśli Twoja witryna korzysta z Content Security Policy, będziesz musiał dodać 'nonce-<value>' i 'strict-dynamic' do script-src, aby Tracy działała poprawnie. Niektóre wtyczki 3rd mogą wymagać dodatkowych dyrektyw. Nonce nie jest obsługiwany w dyrektywie style-src, jeśli używasz tej dyrektywy, musisz dodać 'unsafe-inline', ale należy tego unikać w trybie produkcyjnym.

Przykład konfiguracji dla Nette Framework:

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

Przykład w czystym PHP:

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

Szybsze ładowanie

Podstawowa integracja jest prosta, jednak jeśli posiadasz wolno blokujące się skrypty na stronie, mogą one spowolnić ładowanie Tracy. Rozwiązaniem jest umieszczenie <?php Tracy\Debugger::renderLoader() ?> w swoim szablonie przed jakimikolwiek skryptami:

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

Debugowanie żądań AJAX

Tracy automatycznie przechwytuje żądania AJAX wykonane przy użyciu jQuery lub natywnego interfejsu API fetch. Żądania te są wyświetlane jako dodatkowe wiersze na pasku Tracy, umożliwiając łatwe i wygodne debugowanie AJAX.

Jeśli nie chcesz automatycznie przechwytywać żądań AJAX, możesz wyłączyć tę funkcję, ustawiając zmienną JavaScript:

window.TracyAutoRefresh = false;

W celu ręcznego monitorowania określonych żądań AJAX, dodaj nagłówek HTTP X-Tracy-Ajax z wartością zwracaną przez Tracy.getAjaxHeader(). Oto przykład użycia go z funkcją fetch:

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

Takie podejście pozwala na selektywne debugowanie żądań AJAX.

Przechowywanie danych

Tracy może wyświetlać panele paska Tracy i ekrany Bluescreens dla żądań AJAX i przekierowań. Tracy tworzy własne sesje, przechowuje dane we własnych plikach tymczasowych i używa pliku cookie tracy-session.

Tracy może być również skonfigurowany do korzystania z natywnej sesji PHP, która jest uruchamiana przed włączeniem Tracy:

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

W przypadku, gdy uruchomienie sesji wymaga bardziej złożonej inicjalizacji, można od razu uruchomić Tracy (aby mogła obsłużyć wszelkie pojawiające się błędy), a następnie zainicjować obsługę sesji i ostatecznie poinformować Tracy, że sesja jest gotowa do użycia za pomocą funkcji dispatch():

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

// po czym następuje inicjalizacja sesji
// i rozpocząć sesję
session_start();

Debugger::dispatch();

Funkcja setSessionStorage() istnieje od wersji 2.9, wcześniej Tracy zawsze używała natywnej sesji PHP.

Custom Scrubber

Scrubber jest filtrem, który zapobiega wyciekowi wrażliwych danych z zrzutów, takich jak hasła lub poświadczenia. Filtr ten jest wywoływany dla każdego elementu zrzucanej tablicy lub obiektu i zwraca true, jeśli wartość jest wrażliwa. W takim przypadku zamiast wartości wypisywana jest *****.

// pozwala uniknąć dumpingu wartości kluczy i właściwości takich jak `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, itp.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// używamy go do wszystkich zrzutów wewnątrz BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Logger niestandardowy

Możemy stworzyć własny logger, który będzie rejestrował błędy, niezałatwione wyjątki, a także będzie wywoływany przez Tracy\Debugger::log(). Logger implementuje interfejs Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// wysyła zapytanie do Slacka
	}
}

A następnie aktywujemy go:

Tracy\Debugger::setLogger(new SlackLogger);

Jeśli korzystamy z pełnego Nette Framework, możemy go ustawić w pliku konfiguracyjnym NEON:

services:
	tracy.logger: SlackLogger

Monolog Integration

Pakiet Tracy dostarcza adapter PSR-3, pozwalający na integrację monologu/monologu.

$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'); // pisze: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // pisze: [<TIMESTAMP>] main-channel.WARNING: warning [] []

nginx

Jeśli Tracy nie działa na nginx, prawdopodobnie jest źle skonfigurowany. Jeśli jest coś takiego jak

try_files $uri $uri/ /index.php;

zmień to na

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