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/UI/Sign/SignPresenter.php(21): App\Forms\SignFormFactory->create()
#3 /sandbox/vendor/nette/component-model/src/ComponentModel/Container.php(181): App\UI\Sign\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.4
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: