Nette Documentation Preview

syntax 
Recipes
*******


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

If your site uses Content Security Policy, you'll need to add `'nonce-<value>'` and `'strict-dynamic'` to `script-src` for Tracy to work properly. Some 3rd plugins may require additional directives.
Nonce is not supported in the `style-src` directive, if you use this directive you need to add `'unsafe-inline'`, but this should be avoided in production mode.

Configuration example for [Nette Framework |nette:configuring]:

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

Example in pure PHP:

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


Faster Loading
==============

The basic integration is straightforward, however if you have slow blocking scripts in web page, they can slow the Tracy loading.
The solution is to place `<?php Tracy\Debugger::renderLoader() ?>` into your template before any scripts:

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


Debugging AJAX Requests
=======================

Tracy automatically captures AJAX requests made using jQuery or the native `fetch` API. These requests are displayed as additional rows in the Tracy bar, enabling easy and convenient AJAX debugging.

If you do not want to capture AJAX requests automatically, you can disable this feature by setting the JavaScript variable:

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

For manual monitoring of specific AJAX requests, add the HTTP header `X-Tracy-Ajax` with the value returned by `Tracy.getAjaxHeader()`. Here is an example of using it with the `fetch` function:

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

This approach allows for selective debugging of AJAX requests.


Data Storage
============

Tracy can display Tracy bar panels and Bluescreens for AJAX requests and redirects. Tracy creates its own sessions, stores data in its own temporary files, and uses a `tracy-session` cookie.

Tracy can also be configured to use a native PHP session, which is started before Tracy is turned on:

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

In case starting a session requires more complex initialization, you can start Tracy immediately (so that it can handle any errors that occur) and then initialize the session handler and finally inform Tracy that the session is ready to be used using the `dispatch()` function:

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

// followed by session initialization
// and start the session
session_start();

Debugger::dispatch();
```

The `setSessionStorage()` function has existed since version 2.9, before that Tracy always used the native PHP session.


Custom Scrubber
===============

Scrubber is a filter that prevents sensitive data from leaking from dumps, such as passwords or credentials. The filter is called for each item of the dumped array or object and returns `true` if the value is sensitive. In this case, `*****` is printed instead of the value.

```php
// avoids dumping key values and properties such as `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// we use it for all dumps inside BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;
```


Custom Logger
=============

We can create a custom logger to log errors, uncatched exceptions, and also be called by `Tracy\Debugger::log()`. Logger implements the interface [api:Tracy\ILogger].

```php
use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// sends a request to Slack
	}
}
```

And then we activate it:

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

If we use the full Nette Framework, we can set it in the NEON configuration file:

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


Monolog Integration
-------------------

Tracy package provides a PSR-3 adapter, allowing for integration of [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
=====

If Tracy does not work on nginx, it is probably misconfigured. If there is something like

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

change it to

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

Recipes

Content Security Policy

If your site uses Content Security Policy, you'll need to add 'nonce-<value>' and 'strict-dynamic' to script-src for Tracy to work properly. Some 3rd plugins may require additional directives. Nonce is not supported in the style-src directive, if you use this directive you need to add 'unsafe-inline', but this should be avoided in production mode.

Configuration example for Nette Framework:

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

Example in pure PHP:

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

Faster Loading

The basic integration is straightforward, however if you have slow blocking scripts in web page, they can slow the Tracy loading. The solution is to place <?php Tracy\Debugger::renderLoader() ?> into your template before any scripts:

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

Debugging AJAX Requests

Tracy automatically captures AJAX requests made using jQuery or the native fetch API. These requests are displayed as additional rows in the Tracy bar, enabling easy and convenient AJAX debugging.

If you do not want to capture AJAX requests automatically, you can disable this feature by setting the JavaScript variable:

window.TracyAutoRefresh = false;

For manual monitoring of specific AJAX requests, add the HTTP header X-Tracy-Ajax with the value returned by Tracy.getAjaxHeader(). Here is an example of using it with the fetch function:

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

This approach allows for selective debugging of AJAX requests.

Data Storage

Tracy can display Tracy bar panels and Bluescreens for AJAX requests and redirects. Tracy creates its own sessions, stores data in its own temporary files, and uses a tracy-session cookie.

Tracy can also be configured to use a native PHP session, which is started before Tracy is turned on:

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

In case starting a session requires more complex initialization, you can start Tracy immediately (so that it can handle any errors that occur) and then initialize the session handler and finally inform Tracy that the session is ready to be used using the dispatch() function:

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

// followed by session initialization
// and start the session
session_start();

Debugger::dispatch();

The setSessionStorage() function has existed since version 2.9, before that Tracy always used the native PHP session.

Custom Scrubber

Scrubber is a filter that prevents sensitive data from leaking from dumps, such as passwords or credentials. The filter is called for each item of the dumped array or object and returns true if the value is sensitive. In this case, ***** is printed instead of the value.

// avoids dumping key values and properties such as `password`,
// `password_repeat`, `check_password`, `DATABASE_PASSWORD`, etc.
$scrubber = function(string $key, $value, ?string $class): bool
{
	return preg_match('#password#i', $key) && $value !== null;
};

// we use it for all dumps inside BlueScreen
Tracy\Debugger::getBlueScreen()->scrubber = $scrubber;

Custom Logger

We can create a custom logger to log errors, uncatched exceptions, and also be called by Tracy\Debugger::log(). Logger implements the interface Tracy\ILogger.

use Tracy\ILogger;

class SlackLogger implements ILogger
{
	public function log($value, $priority = ILogger::INFO)
	{
		// sends a request to Slack
	}
}

And then we activate it:

Tracy\Debugger::setLogger(new SlackLogger);

If we use the full Nette Framework, we can set it in the NEON configuration file:

services:
	tracy.logger: SlackLogger

Monolog Integration

Tracy package provides a PSR-3 adapter, allowing for integration of 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

If Tracy does not work on nginx, it is probably misconfigured. If there is something like

try_files $uri $uri/ /index.php;

change it to

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