Nette Documentation Preview

syntax 
Receitas
********


Política de Segurança de Conteúdo .[#toc-content-security-policy]
=================================================================

Se seu site utiliza a Política de Segurança de Conteúdo, você precisará acrescentar `'nonce-<value>'` e `'strict-dynamic'` a `script-src` para que Tracy funcione corretamente. Alguns 3º plugins podem exigir diretrizes adicionais.
Nonce não é suportado na diretiva `style-src`, se você usar esta diretiva você precisa adicionar `'unsafe-inline'`, mas isto deve ser evitado no modo de produção.

Exemplo de configuração para [Nette Framework |nette:configuring]:

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

Exemplo em PHP puro:

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


Carregamento mais rápido .[#toc-faster-loading]
===============================================

A integração básica é simples, porém se você tiver scripts de bloqueio lentos na página web, eles podem retardar o carregamento do Tracy.
A solução é colocar `<?php Tracy\Debugger::renderLoader() ?>` em seu modelo antes de qualquer roteiro:

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


Depuração de solicitações AJAX .[#toc-debugging-ajax-requests]
==============================================================

O Tracy captura automaticamente as solicitações AJAX feitas com jQuery ou com a API nativa `fetch`. Essas solicitações são exibidas como linhas adicionais na barra do Tracy, permitindo uma depuração AJAX fácil e conveniente.

Se não quiser capturar automaticamente as solicitações AJAX, você poderá desativar esse recurso definindo a variável JavaScript:

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

Para o monitoramento manual de solicitações AJAX específicas, adicione o cabeçalho HTTP `X-Tracy-Ajax` com o valor retornado por `Tracy.getAjaxHeader()`. Aqui está um exemplo de uso com a função `fetch`:

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

Essa abordagem permite a depuração seletiva de solicitações AJAX.


Armazenamento de dados .[#toc-data-storage]
===========================================

O Tracy pode exibir painéis de barras Tracy e Bluescreens para solicitações e redirecionamentos AJAX. O Tracy cria suas próprias sessões, armazena dados em seus próprios arquivos temporários e usa um cookie `tracy-session`.

Tracy também pode ser configurado para usar uma sessão PHP nativa, que é iniciada antes de Tracy ser ligado:

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

Caso o início de uma sessão requeira uma inicialização mais complexa, você pode iniciar Tracy imediatamente (para que ele possa lidar com quaisquer erros que ocorram) e então inicializar o manipulador da sessão e finalmente informar Tracy que a sessão está pronta para ser usada usando a função `dispatch()`:

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

// seguido pela inicialização da sessão
// e iniciar a sessão
session_start();

Debugger::dispatch();
```

A função `setSessionStorage()` existe desde a versão 2.9, antes disso Tracy sempre usou a sessão PHP nativa.


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

O Scrubber é um filtro que evita que dados sensíveis vazem de lixões, tais como senhas ou credenciais. O filtro é chamado para cada item da matriz ou objeto despejado e retorna `true` se o valor for sensível. Neste caso, `*****` é impresso ao invés do valor.

```php
// evita o despejo de valores e propriedades chave como "palavras-chave",
// Palavras_senhas_repetição', 'verificar_senhas', 'DATABASE_PASSWORD', etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// nós o utilizamos para todas as lixeiras dentro da BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Registrador personalizado .[#toc-custom-logger]
===============================================

Podemos criar um registrador personalizado para registrar erros, exceções inigualáveis, e também ser chamado por `Tracy\Debugger::log()`. O logger implementa a interface [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// envia um pedido para Slack
	}
}
```

E então o ativamos:

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

Se utilizarmos toda a estrutura Nette, podemos configurá-la no arquivo de configuração NEON:

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


Integração do Monolog .[#toc-monolog-integration]
-------------------------------------------------

O pacote Tracy fornece um adaptador PSR-3, permitindo a integração de [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'); // escreve: [<TIMESTAMP>] main-channel.INFO: info [] [] []
Debugger::log('warning', Debugger::WARNING); // escreve: [<TIMESTAMP>] main-channel.WARNING: warning [] [] []
```


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

Se Tracy não trabalha com nginx, provavelmente está mal configurado. Se houver algo como

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

mudá-lo para

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

Receitas

Política de Segurança de Conteúdo

Se seu site utiliza a Política de Segurança de Conteúdo, você precisará acrescentar 'nonce-<value>' e 'strict-dynamic' a script-src para que Tracy funcione corretamente. Alguns 3º plugins podem exigir diretrizes adicionais. Nonce não é suportado na diretiva style-src, se você usar esta diretiva você precisa adicionar 'unsafe-inline', mas isto deve ser evitado no modo de produção.

Exemplo de configuração para Nette Framework:

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

Exemplo em PHP puro:

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

Carregamento mais rápido

A integração básica é simples, porém se você tiver scripts de bloqueio lentos na página web, eles podem retardar o carregamento do Tracy. A solução é colocar <?php Tracy\Debugger::renderLoader() ?> em seu modelo antes de qualquer roteiro:

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

Depuração de solicitações AJAX

O Tracy captura automaticamente as solicitações AJAX feitas com jQuery ou com a API nativa fetch. Essas solicitações são exibidas como linhas adicionais na barra do Tracy, permitindo uma depuração AJAX fácil e conveniente.

Se não quiser capturar automaticamente as solicitações AJAX, você poderá desativar esse recurso definindo a variável JavaScript:

window.TracyAutoRefresh = false;

Para o monitoramento manual de solicitações AJAX específicas, adicione o cabeçalho HTTP X-Tracy-Ajax com o valor retornado por Tracy.getAjaxHeader(). Aqui está um exemplo de uso com a função fetch:

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

Essa abordagem permite a depuração seletiva de solicitações AJAX.

Armazenamento de dados

O Tracy pode exibir painéis de barras Tracy e Bluescreens para solicitações e redirecionamentos AJAX. O Tracy cria suas próprias sessões, armazena dados em seus próprios arquivos temporários e usa um cookie tracy-session.

Tracy também pode ser configurado para usar uma sessão PHP nativa, que é iniciada antes de Tracy ser ligado:

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

Caso o início de uma sessão requeira uma inicialização mais complexa, você pode iniciar Tracy imediatamente (para que ele possa lidar com quaisquer erros que ocorram) e então inicializar o manipulador da sessão e finalmente informar Tracy que a sessão está pronta para ser usada usando a função dispatch():

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

// seguido pela inicialização da sessão
// e iniciar a sessão
session_start();

Debugger::dispatch();

A função setSessionStorage() existe desde a versão 2.9, antes disso Tracy sempre usou a sessão PHP nativa.

Scrubber personalizado

O Scrubber é um filtro que evita que dados sensíveis vazem de lixões, tais como senhas ou credenciais. O filtro é chamado para cada item da matriz ou objeto despejado e retorna true se o valor for sensível. Neste caso, ***** é impresso ao invés do valor.

// evita o despejo de valores e propriedades chave como "palavras-chave",
// Palavras_senhas_repetição', 'verificar_senhas', 'DATABASE_PASSWORD', etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// nós o utilizamos para todas as lixeiras dentro da BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Registrador personalizado

Podemos criar um registrador personalizado para registrar erros, exceções inigualáveis, e também ser chamado por Tracy\Debugger::log(). O logger implementa a interface Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// envia um pedido para Slack
	}
}

E então o ativamos:

Tracy\Debugger::setLogger(new SlackLogger);

Se utilizarmos toda a estrutura Nette, podemos configurá-la no arquivo de configuração NEON:

services:
	tracy.logger: SlackLogger

Integração do Monolog

O pacote Tracy fornece um adaptador PSR-3, permitindo a integração de 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'); // escreve: [<TIMESTAMP>] main-channel.INFO: info [] [] []
Debugger::log('warning', Debugger::WARNING); // escreve: [<TIMESTAMP>] main-channel.WARNING: warning [] [] []

nginx

Se Tracy não trabalha com nginx, provavelmente está mal configurado. Se houver algo como

try_files $uri $uri/ /index.php;

mudá-lo para

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