Nette Documentation Preview

syntax 
Návody
******


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

Pokud váš web používá Content Security Policy, budete muset přidat stejné `'nonce-<value>'` a `'strict-dynamic'` do `script-src`, aby Tracy správně fungovala. Některé doplňky třetích stran mohou vyžadovat další nastavení.
Nonce není podporována v direktivě `style-src`, pokud tuto direktivu používáte, musíte přidat `'unsafe-inline'`, ale v produkčním režimu byste se tomu měli vyhnout.

Příklad konfigurace pro [Nette Framework |nette:configuring]:

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

Příklad v čistém PHP:

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


Rychlejší načítání
==================

Spuštění je přímočaré, pokud však máte na webové stránce pomalu načítající se blokující skripty, mohou zpomalit načítání Tracy.
Řešením je umístit `<?php Tracy\Debugger::renderLoader() ?>` do vaší šablony před všechny skripty:

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


Ladění AJAXový požadavků
========================

Tracy automaticky zachycuje AJAXové požadavky vytvořené pomocí jQuery nebo nativního API `fetch`. Požadavky jsou v liště Tracy zobrazeny jako další řádky, což umožňuje snadné a pohodlné ladění AJAXu.

Pokud nechcete AJAXové požadavky zachycovat automaticky, můžete tuto funkci zakázat nastavením JavaScriptové proměnné:

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

Pro ruční monitorování specifických AJAX požadavků přidejte HTTP hlavičku `X-Tracy-Ajax` s hodnotou, kterou vrátí `Tracy.getAjaxHeader()`. Zde je příklad použití s funkcí `fetch`:

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

Tento přístup umožňuje selektivní ladění AJAX požadavků.


Datové úložiště
===============

Tracy umí zobrazit panely v Tracy baru a Bluescreeny pro AJAXové požadavky a přesměrovaní. Tracy si vytváří vlastní session, data uchovává ve vlastních dočasných souborech a používá cookie `tracy-session`.

Tracy lze nakonfigurovat také tak, aby používala nativní PHP session, kterou nastartujeme ještě před zapnutím Tracy:

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

V případě, že nastartování session vyžaduje složitější inicializaci, můžete Tracy spustit ihned (aby mohla zpracovat případné vzniklé chyby) a poté inicializovat obsluhu relace a nakonec informovat Tracy, že relace je připravena k použití pomocí funkce `dispatch()`:

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

// následuje inicializace session
// a spuštění session
session_start();

Debugger::dispatch();
```

Funkce `setSessionStorage()` existuje od verze 2.9, předtím používala Tracy nativní PHP session vždy.


Vlastní scrubber
================

Scrubber je filtr, který zabraňuje úniku citlivých dat při dumpování, jako jsou hesla nebo přístupové údaje. Filtr se volá pro každý prvek dumpovaného pole nebo objektu a vrací `true`, pokud je hodnota citlivá. V takovém případě se místo hodnoty vypíše `*****`.

```php
// zamezí vypsaní hodnot klíčů a properties jako `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, apod.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// použijeme jej pro všechny dumpy uvnitř BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Vlastní logger
==============

Můžeme si vytvořit vlastní logger, který bude logovat chyby, nezachycené výjimky a také bude vyvolán metodou `Tracy\Debugger::log()`. Logger implementuje rozhraní [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// pošle request na Slack
	}
}
```

A následně jej aktivujeme:

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

Pokud používáme plný Nette Framework, můžete jej nastavit v konfiguračním NEON souboru:

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


Integrace monologu
------------------

Balíček Tracy poskytuje adaptér PSR-3, který umožňuje integraci [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'); // writes: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // writes: [<TIMESTAMP>] main-channel.WARNING: warning [] []
```


nginx
=====

Pokud vám nefunguje Tracy na serveru nginx, nespíš je špatně nakonfigurovaný. Pokud je v konfiguraci něco jako:

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

změňte to na:

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

Návody

Content Security Policy

Pokud váš web používá Content Security Policy, budete muset přidat stejné 'nonce-<value>' a 'strict-dynamic' do script-src, aby Tracy správně fungovala. Některé doplňky třetích stran mohou vyžadovat další nastavení. Nonce není podporována v direktivě style-src, pokud tuto direktivu používáte, musíte přidat 'unsafe-inline', ale v produkčním režimu byste se tomu měli vyhnout.

Příklad konfigurace pro Nette Framework:

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

Příklad v čistém PHP:

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

Rychlejší načítání

Spuštění je přímočaré, pokud však máte na webové stránce pomalu načítající se blokující skripty, mohou zpomalit načítání Tracy. Řešením je umístit <?php Tracy\Debugger::renderLoader() ?> do vaší šablony před všechny skripty:

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

Ladění AJAXový požadavků

Tracy automaticky zachycuje AJAXové požadavky vytvořené pomocí jQuery nebo nativního API fetch. Požadavky jsou v liště Tracy zobrazeny jako další řádky, což umožňuje snadné a pohodlné ladění AJAXu.

Pokud nechcete AJAXové požadavky zachycovat automaticky, můžete tuto funkci zakázat nastavením JavaScriptové proměnné:

window.TracyAutoRefresh = false;

Pro ruční monitorování specifických AJAX požadavků přidejte HTTP hlavičku X-Tracy-Ajax s hodnotou, kterou vrátí Tracy.getAjaxHeader(). Zde je příklad použití s funkcí fetch:

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

Tento přístup umožňuje selektivní ladění AJAX požadavků.

Datové úložiště

Tracy umí zobrazit panely v Tracy baru a Bluescreeny pro AJAXové požadavky a přesměrovaní. Tracy si vytváří vlastní session, data uchovává ve vlastních dočasných souborech a používá cookie tracy-session.

Tracy lze nakonfigurovat také tak, aby používala nativní PHP session, kterou nastartujeme ještě před zapnutím Tracy:

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

V případě, že nastartování session vyžaduje složitější inicializaci, můžete Tracy spustit ihned (aby mohla zpracovat případné vzniklé chyby) a poté inicializovat obsluhu relace a nakonec informovat Tracy, že relace je připravena k použití pomocí funkce dispatch():

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

// následuje inicializace session
// a spuštění session
session_start();

Debugger::dispatch();

Funkce setSessionStorage() existuje od verze 2.9, předtím používala Tracy nativní PHP session vždy.

Vlastní scrubber

Scrubber je filtr, který zabraňuje úniku citlivých dat při dumpování, jako jsou hesla nebo přístupové údaje. Filtr se volá pro každý prvek dumpovaného pole nebo objektu a vrací true, pokud je hodnota citlivá. V takovém případě se místo hodnoty vypíše *****.

// zamezí vypsaní hodnot klíčů a properties jako `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, apod.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// použijeme jej pro všechny dumpy uvnitř BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Vlastní logger

Můžeme si vytvořit vlastní logger, který bude logovat chyby, nezachycené výjimky a také bude vyvolán metodou Tracy\Debugger::log(). Logger implementuje rozhraní Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// pošle request na Slack
	}
}

A následně jej aktivujeme:

Tracy\Debugger::setLogger(new SlackLogger);

Pokud používáme plný Nette Framework, můžete jej nastavit v konfiguračním NEON souboru:

services:
	tracy.logger: SlackLogger

Integrace monologu

Balíček Tracy poskytuje adaptér PSR-3, který umožňuje integraci 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'); // writes: [<TIMESTAMP>] main-channel.INFO: info [] []
Debugger::log('warning', Debugger::WARNING); // writes: [<TIMESTAMP>] main-channel.WARNING: warning [] []

nginx

Pokud vám nefunguje Tracy na serveru nginx, nespíš je špatně nakonfigurovaný. Pokud je v konfiguraci něco jako:

try_files $uri $uri/ /index.php;

změňte to na:

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