Nette Documentation Preview

syntax
Começando com Tracy
*******************

<div class=perex>

A biblioteca Tracy é uma ajuda útil para os programadores PHP do dia-a-dia. Ela ajuda você a:

- detectar e corrigir rapidamente os erros
- erros de registro
- variáveis de despejo
- medir o tempo de execução dos scripts/queries
- ver consumo de memória

</div>


O PHP é uma linguagem perfeita para fazer erros dificilmente detectáveis, pois dá grande flexibilidade aos programadores. Tracy\Debugger é mais valioso por causa disso. É uma ferramenta definitiva entre as ferramentas de diagnóstico.

Se você está encontrando Tracy pela primeira vez, acredite, sua vida começa a ser dividida em uma antes da Tracy e uma com ela. Bem-vindo à parte boa!


Instalação e requisitos .[#toc-installation-and-requirements]
=============================================================

A melhor maneira de instalar Tracy é [baixar o pacote mais recente](https://github.com/nette/tracy/releases) ou usar o Composer:

```shell
composer require tracy/tracy
```

Alternativamente, você pode baixar o pacote completo ou o arquivo [tracy.phar. |https://github.com/nette/tracy/releases]


Utilização .[#toc-usage]
========================

Tracy é ativado chamando o método `Tracy\Debugger::enable()' o mais rápido possível no início do programa, antes que qualquer saída seja enviada:

```php
use Tracy\Debugger;

require 'vendor/autoload.php'; // alternativamente tracy.phar

Debugger::enable();
```

A primeira coisa que você vai notar na página é o Tracy Bar no canto inferior direito. Se você não a vir, isso pode significar que Tracy está funcionando no modo de produção.
Isto porque Tracy só é visível no local por razões de segurança. Para testar se ela funciona, você pode colocá-la temporariamente em modo de desenvolvimento usando o parâmetro `Debugger::enable(Debugger::Development)`.


Barra Tracy .[#toc-tracy-bar]
=============================

O Tracy Bar é um painel flutuante. Ela é exibida no canto inferior direito de uma página. Você pode movê-la usando o mouse. Ela lembrará sua posição após a recarga da página.

[* tracy-bar.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Você pode adicionar outros painéis úteis à Barra Tracy. Você pode encontrar painéis interessantes em [addons |https://componette.org] ou você pode [criar seus próprios |extensions].

Se você não quiser mostrar o Tracy Bar, preparar:

```php
Debugger::$showBar = false;
```


Visualização de erros e exceções .[#toc-visualization-of-errors-and-exceptions]
===============================================================================

Certamente, você sabe como PHP relata erros: há algo assim no código fonte da página:

/--pre .{font-size: 90%}
<b>Parse error</b>:  syntax error, unexpected '}' in <b>HomePresenter.php</b> on line <b>15</b>
\--

ou exceção não cautelosa:

/--pre .{font-size: 90%}
<b>Fatal error</b>:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in <b>/sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php</b> on line <b>100</b><br />
\--

Não é tão fácil navegar através desta saída. Se você habilitar Tracy, tanto os erros quanto as exceções serão exibidos de uma forma completamente diferente:

[* tracy-exception.webp .{url:-} *]

A mensagem de erro grita literalmente. Você pode ver uma parte do código fonte com a linha destacada onde o erro ocorreu. Uma mensagem explica claramente um erro. O site inteiro é [interativo, experimente-o](https://nette.github.io/tracy/tracy-exception.html).

E você sabe o que mais? Os erros fatais são capturados e exibidos da mesma maneira. Não há necessidade de instalar nenhuma extensão (clique para exemplo ao vivo):

[* tracy-error.webp .{url:-} *]

Erros como um erro de digitação em um nome de variável ou uma tentativa de abrir um arquivo inexistente geram relatórios de nível E_NOTICE ou E_WARNING. Estes podem ser facilmente ignorados e/ou podem ser completamente escondidos em um layout gráfico de uma página web. Deixe Tracy gerenciá-los:

[* tracy-notice2.webp *]:https://nette.github.io/tracy/tracy-debug-bar.html

Ou eles podem ser exibidos como erros:

```php
Debugger::$strictMode = true; // exibir todos os erros
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos os erros, exceto avisos depreciados
```

[* tracy-notice.webp .{url:-} *]

Nota: Tracy quando ativado muda o nível de relatório de erro para E_ALL. Se você quiser mudar isto, faça-o depois de ligar para `enable()`.


Desenvolvimento vs Modo de Produção .[#toc-development-vs-production-mode]
==========================================================================

Como você pode ver, Tracy é bastante faladora, o que pode ser apreciado no ambiente de desenvolvimento, enquanto no servidor de produção causaria um desastre. Isso porque nenhuma informação de depuração deve ser exibida lá. Portanto, Tracy tem **detecção automática do ambiente*** e se o exemplo for executado em um servidor ao vivo, o erro será registrado em vez de exibido, e o visitante verá apenas uma mensagem amigável:

[* tracy-error2.webp .{url:-} *]

O modo de produção suprime a exibição de todas as informações de depuração enviadas usando [dump() |dumper], e, é claro, também todas as mensagens de erro geradas pelo PHP. Portanto, se você esqueceu algum `dump($obj)` no código, não precisa se preocupar, nada será exibido no servidor de produção.

Como funciona a autodetecção de modo? O modo é desenvolvimento se a aplicação estiver rodando no localhost (ou seja, endereço IP `127.0.0.1` ou `::1`) e não houver proxy (ou seja, seu cabeçalho HTTP). Caso contrário, ele é executado em modo de produção.

Se você quiser ativar o modo de desenvolvimento em outros casos, por exemplo, para desenvolvedores acessando de um endereço IP específico, você pode especificá-lo como um parâmetro do método `enable()`:

```php
Debugger::enable('23.75.345.200'); // você também pode fornecer um conjunto de endereços IP
```

Definitivamente, recomendamos combinar o endereço IP com um cookie. Armazene um token secreto, por exemplo, `secret1234`, no cookie `tracy-debug` e, desta forma, ative o modo de desenvolvimento somente para desenvolvedores que acessem de um endereço IP específico e que tenham o token mencionado no cookie:

```php
Debugger::enable('secret1234@23.75.345.200');
```

Você também pode definir diretamente o modo de desenvolvimento/produção usando as constantes `Debugger::Development` ou `Debugger::Production` como parâmetro do método `enable()`.

.[note]
Se você usar o Nette Framework, dê uma olhada em como [definir o modo para ele |application:bootstrap#Development vs Production Mode], e então ele também será usado para Tracy.


Registro de erros .[#toc-error-logging]
=======================================

No modo de produção, Tracy registra automaticamente todos os erros e exceções a um registro de texto. Para que o registro ocorra, é necessário definir o caminho absoluto para o diretório de registro para a variável `$logDirectory` ou passá-lo como o segundo parâmetro para o método `enable()`:

```php
Debugger::$logDirectory = __DIR__ . '/log';
```

O registro de erros é extremamente útil. Imagine que todos os usuários de sua aplicação são na verdade testadores beta que fazem um trabalho de primeira linha para encontrar erros gratuitamente, e você seria tolo em jogar fora seus valiosos relatórios sem ser notado no caixote do lixo.

Se você precisar registrar suas próprias mensagens ou se tiver que pegar exceções, use o método `log()`:

```php
Depurador::log('Unexpected error'); // mensagem de texto

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // exceção de log
	// ou
	Debugger::log($e, Debugger::ERROR); // também envia uma notificação por e-mail
}
```

If you want Tracy to log PHP errors like `E_NOTICE` or `E_WARNING` with detailed information (HTML report), set `Debugger::$logSeverity`:

```php
Debugger::$logSeverity = E_NOTICE | E_WARNING;
```

Para um verdadeiro profissional, o registro de erros é uma fonte crucial de informação e ele ou ela quer ser notificado sobre qualquer novo erro imediatamente. Tracy o ajuda. Ela é capaz de enviar um e-mail para cada novo registro de erro. A variável $email identifica para onde enviar esses e-mails:

```php
Debugger::$email = 'admin@example.com';
```

Se você usar toda a estrutura Nette, você pode definir esta e outras no [arquivo de configuração |nette:configuring].

Para proteger sua caixa de e-mail contra inundações, Tracy envia **somente uma mensagem** e cria um arquivo `email-sent`. Quando um desenvolvedor recebe a notificação por e-mail, ele verifica o registro, corrige sua aplicação e apaga o arquivo de monitoramento `email-sent`. Isto ativa o envio do e-mail novamente.


Arquivos de abertura no editor .[#toc-opening-files-in-the-editor]
==================================================================

Quando a página de erro for exibida, você pode clicar nos nomes dos arquivos e eles serão abertos em seu editor com o cursor na linha correspondente. Os arquivos também podem ser criados (ação `create file`) ou corrigidos com bugs (ação `fix it`). Para isso, você precisa [configurar o navegador e o sistema |open-files-in-ide].


Versões PHP suportadas .[#toc-supported-php-versions]
=====================================================

| Tracy | compatível com PHP
|-----------|--------------------
| Tracy 2.10 – 3.0 | PHP 8.0 – 8.3
| Tracy 2.9 | PHP 7.2 - 8.2
| Tracy 2.8 | PHP 7.2 - 8.1
| Tracy 2.6 - 2.7 | PHP 7.1 - 8.0
| Tracy 2.5 | PHP 5.4 - 7.4
| Tracy 2.4 | PHP 5.4 - 7.2

Aplica-se às últimas versões de remendos.


Portos .[#toc-ports]
====================

Esta é uma lista de portos não-oficiais para outras estruturas e CMS:

- [Drupal 7](https://www.drupal.org/project/traced)
- Laravel framework: [recca0120/laravel-tracy](https://github.com/recca0120/laravel-tracy), [whipsterCZ/laravel-tracy](https://github.com/whipsterCZ/laravel-tracy)
- [OpenCart](https://github.com/BurdaPraha/oc_tracy)
- [ProcessWire CMS/CMF](https://github.com/adrianbj/TracyDebugger)
- [Slim Framework](https://github.com/runcmf/runtracy)
- Symfony framework: [kutny/tracy-bundle](https://github.com/kutny/tracy-bundle), [VasekPurchart/Tracy-Blue-Screen-Bundle](https://github.com/VasekPurchart/Tracy-Blue-Screen-Bundle)
- [Wordpress](https://github.com/ktstudio/WP-Tracy)

Começando com Tracy

A biblioteca Tracy é uma ajuda útil para os programadores PHP do dia-a-dia. Ela ajuda você a:

  • detectar e corrigir rapidamente os erros
  • erros de registro
  • variáveis de despejo
  • medir o tempo de execução dos scripts/queries
  • ver consumo de memória

O PHP é uma linguagem perfeita para fazer erros dificilmente detectáveis, pois dá grande flexibilidade aos programadores. Tracy\Debugger é mais valioso por causa disso. É uma ferramenta definitiva entre as ferramentas de diagnóstico.

Se você está encontrando Tracy pela primeira vez, acredite, sua vida começa a ser dividida em uma antes da Tracy e uma com ela. Bem-vindo à parte boa!

Instalação e requisitos

A melhor maneira de instalar Tracy é baixar o pacote mais recente ou usar o Composer:

composer require tracy/tracy

Alternativamente, você pode baixar o pacote completo ou o arquivo tracy.phar.

Utilização

Tracy é ativado chamando o método `Tracy\Debugger::enable()' o mais rápido possível no início do programa, antes que qualquer saída seja enviada:

use Tracy\Debugger;

require 'vendor/autoload.php'; // alternativamente tracy.phar

Debugger::enable();

A primeira coisa que você vai notar na página é o Tracy Bar no canto inferior direito. Se você não a vir, isso pode significar que Tracy está funcionando no modo de produção. Isto porque Tracy só é visível no local por razões de segurança. Para testar se ela funciona, você pode colocá-la temporariamente em modo de desenvolvimento usando o parâmetro Debugger::enable(Debugger::Development).

Barra Tracy

O Tracy Bar é um painel flutuante. Ela é exibida no canto inferior direito de uma página. Você pode movê-la usando o mouse. Ela lembrará sua posição após a recarga da página.

Você pode adicionar outros painéis úteis à Barra Tracy. Você pode encontrar painéis interessantes em addons ou você pode criar seus próprios.

Se você não quiser mostrar o Tracy Bar, preparar:

Debugger::$showBar = false;

Visualização de erros e exceções

Certamente, você sabe como PHP relata erros: há algo assim no código fonte da página:

Parse error:  syntax error, unexpected '}' in HomePresenter.php on line 15

ou exceção não cautelosa:

Fatal error:  Uncaught Nette\MemberAccessException: Call to undefined method Nette\Application\UI\Form::addTest()? in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php:100
Stack trace:
#0 /sandbox/vendor/nette/utils/src/Utils/Object.php(75): Nette\Utils\ObjectMixin::call(Object(Nette\Application\UI\Form), 'addTest', Array)
#1 /sandbox/app/forms/SignFormFactory.php(32): Nette\Object->__call('addTest', Array)
#2 /sandbox/app/presenters/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\Presenters\SignPresenter->createComponentSignInForm('signInForm')
#4 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(139): Nette\ComponentModel\Container->createComponent('signInForm')
#5 /sandbox/temp/cache/latte/15206b353f351f6bfca2c36cc.php(17): Nette\ComponentModel\Co in /sandbox/vendor/nette/utils/src/Utils/ObjectMixin.php on line 100

Não é tão fácil navegar através desta saída. Se você habilitar Tracy, tanto os erros quanto as exceções serão exibidos de uma forma completamente diferente:

A mensagem de erro grita literalmente. Você pode ver uma parte do código fonte com a linha destacada onde o erro ocorreu. Uma mensagem explica claramente um erro. O site inteiro é interativo, experimente-o.

E você sabe o que mais? Os erros fatais são capturados e exibidos da mesma maneira. Não há necessidade de instalar nenhuma extensão (clique para exemplo ao vivo):

Erros como um erro de digitação em um nome de variável ou uma tentativa de abrir um arquivo inexistente geram relatórios de nível E_NOTICE ou E_WARNING. Estes podem ser facilmente ignorados e/ou podem ser completamente escondidos em um layout gráfico de uma página web. Deixe Tracy gerenciá-los:

Ou eles podem ser exibidos como erros:

Debugger::$strictMode = true; // exibir todos os erros
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos os erros, exceto avisos depreciados

Nota: Tracy quando ativado muda o nível de relatório de erro para E_ALL. Se você quiser mudar isto, faça-o depois de ligar para enable().

Desenvolvimento vs Modo de Produção

Como você pode ver, Tracy é bastante faladora, o que pode ser apreciado no ambiente de desenvolvimento, enquanto no servidor de produção causaria um desastre. Isso porque nenhuma informação de depuração deve ser exibida lá. Portanto, Tracy tem **detecção automática do ambiente*** e se o exemplo for executado em um servidor ao vivo, o erro será registrado em vez de exibido, e o visitante verá apenas uma mensagem amigável:

O modo de produção suprime a exibição de todas as informações de depuração enviadas usando dump(), e, é claro, também todas as mensagens de erro geradas pelo PHP. Portanto, se você esqueceu algum dump($obj) no código, não precisa se preocupar, nada será exibido no servidor de produção.

Como funciona a autodetecção de modo? O modo é desenvolvimento se a aplicação estiver rodando no localhost (ou seja, endereço IP 127.0.0.1 ou ::1) e não houver proxy (ou seja, seu cabeçalho HTTP). Caso contrário, ele é executado em modo de produção.

Se você quiser ativar o modo de desenvolvimento em outros casos, por exemplo, para desenvolvedores acessando de um endereço IP específico, você pode especificá-lo como um parâmetro do método enable():

Debugger::enable('23.75.345.200'); // você também pode fornecer um conjunto de endereços IP

Definitivamente, recomendamos combinar o endereço IP com um cookie. Armazene um token secreto, por exemplo, secret1234, no cookie tracy-debug e, desta forma, ative o modo de desenvolvimento somente para desenvolvedores que acessem de um endereço IP específico e que tenham o token mencionado no cookie:

Debugger::enable('secret1234@23.75.345.200');

Você também pode definir diretamente o modo de desenvolvimento/produção usando as constantes Debugger::Development ou Debugger::Production como parâmetro do método enable().

Se você usar o Nette Framework, dê uma olhada em como definir o modo para ele, e então ele também será usado para Tracy.

Registro de erros

No modo de produção, Tracy registra automaticamente todos os erros e exceções a um registro de texto. Para que o registro ocorra, é necessário definir o caminho absoluto para o diretório de registro para a variável $logDirectory ou passá-lo como o segundo parâmetro para o método enable():

Debugger::$logDirectory = __DIR__ . '/log';

O registro de erros é extremamente útil. Imagine que todos os usuários de sua aplicação são na verdade testadores beta que fazem um trabalho de primeira linha para encontrar erros gratuitamente, e você seria tolo em jogar fora seus valiosos relatórios sem ser notado no caixote do lixo.

Se você precisar registrar suas próprias mensagens ou se tiver que pegar exceções, use o método log():

Depurador::log('Unexpected error'); // mensagem de texto

try {
	criticalOperation();
} catch (Exception $e) {
	Debugger::log($e); // exceção de log
	// ou
	Debugger::log($e, Debugger::ERROR); // também envia uma notificação por e-mail
}

If you want Tracy to log PHP errors like E_NOTICE or E_WARNING with detailed information (HTML report), set Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Para um verdadeiro profissional, o registro de erros é uma fonte crucial de informação e ele ou ela quer ser notificado sobre qualquer novo erro imediatamente. Tracy o ajuda. Ela é capaz de enviar um e-mail para cada novo registro de erro. A variável $email identifica para onde enviar esses e-mails:

Debugger::$email = 'admin@example.com';

Se você usar toda a estrutura Nette, você pode definir esta e outras no arquivo de configuração.

Para proteger sua caixa de e-mail contra inundações, Tracy envia somente uma mensagem e cria um arquivo email-sent. Quando um desenvolvedor recebe a notificação por e-mail, ele verifica o registro, corrige sua aplicação e apaga o arquivo de monitoramento email-sent. Isto ativa o envio do e-mail novamente.

Arquivos de abertura no editor

Quando a página de erro for exibida, você pode clicar nos nomes dos arquivos e eles serão abertos em seu editor com o cursor na linha correspondente. Os arquivos também podem ser criados (ação create file) ou corrigidos com bugs (ação fix it). Para isso, você precisa configurar o navegador e o sistema.

Versões PHP suportadas

Tracy compatível com PHP
Tracy 2.10 – 3.0 PHP 8.0 – 8.3
Tracy 2.9 PHP 7.2 – 8.2
Tracy 2.8 PHP 7.2 – 8.1
Tracy 2.6 – 2.7 PHP 7.1 – 8.0
Tracy 2.5 PHP 5.4 – 7.4
Tracy 2.4 PHP 5.4 – 7.2

Aplica-se às últimas versões de remendos.

Portos

Esta é uma lista de portos não-oficiais para outras estruturas e CMS: