Começando com o Tracy

A biblioteca Tracy é uma ajudante diária útil para o programador PHP. Ela ajudará você a:

  • detectar e corrigir erros rapidamente
  • registrar erros
  • exibir variáveis
  • medir o tempo de execução de scripts e consultas de banco de dados
  • monitorar o consumo de memória

PHP é uma linguagem perfeita para cometer erros difíceis de detectar, pois oferece aos desenvolvedores uma liberdade considerável. Isso torna a ferramenta de depuração Tracy ainda mais valiosa. Entre as ferramentas de diagnóstico para PHP, ela representa o ápice absoluto.

Se você está encontrando o Tracy pela primeira vez hoje, acredite que sua vida começará a se dividir entre antes do Tracy e com ele. Bem-vindo à parte melhor!

Instalação

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

composer require tracy/tracy

Você também pode baixar o pacote completo como um arquivo tracy.phar.

Uso

Ativamos o Tracy chamando o método Tracy\Debugger::enable() o mais cedo possível no início do programa, antes de enviar qualquer saída:

use Tracy\Debugger;

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

Debugger::enable();

A primeira coisa que você notará na página é a Tracy Bar no canto inferior direito. Se você não a vir, pode significar que o Tracy está rodando em modo de produção. Por razões de segurança, o Tracy só é visível no localhost. Para testar se está funcionando, você pode temporariamente mudá-lo para o modo de desenvolvimento usando o parâmetro Debugger::enable(Debugger::Development).

Tracy Bar

A Tracy Bar é um painel flutuante que aparece no canto inferior direito da página. Podemos movê-la com o mouse e ela lembrará sua posição após recarregar a página.

É possível adicionar outros painéis úteis à Tracy Bar. Você pode encontrar muitos deles em add-ons, ou pode até escrever o seu próprio.

Se você não quiser exibir a Tracy Bar, defina:

Debugger::$showBar = false;

Visualização de erros e exceções

Você certamente sabe como o PHP relata erros: ele imprime algo assim no código-fonte da página:

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

ou com uma exceção não capturada:

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

Navegar por essa saída não é exatamente fácil. Se ativarmos o Tracy, o erro ou a exceção será exibido de uma forma completamente diferente:

A mensagem de erro literalmente grita. Vemos uma parte do código-fonte com a linha destacada onde o erro ocorreu, e a informação Call to undefined method Nette\Http\User::isLogedIn() explica claramente qual é o erro. Além disso, toda a página é interativa; podemos clicar para obter mais detalhes. Experimente.

E sabe de uma coisa? Ele captura e exibe até mesmo erros fatais desta forma. Sem a necessidade de instalar nenhuma extensão.

Erros como um erro de digitação no nome de uma 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 no layout da página e podem até não ser visíveis (a menos que você olhe o código-fonte).

Ou podem ser exibidos da mesma forma que os erros:

Debugger::$strictMode = true; // exibe todos os erros
Debugger::$strictMode = E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED; // todos os erros exceto avisos de depreciação

Nota: Após a ativação, o Tracy altera o nível de relatório de erros para E_ALL. Se você quiser alterar esse valor, faça-o após chamar enable().

Modo de desenvolvimento vs. produção

Como você pode ver, o Tracy é bastante verboso, o que pode ser apreciado em um ambiente de desenvolvimento, enquanto em um servidor de produção causaria um desastre. Nenhuma informação de depuração deve ser exibida lá. Portanto, o Tracy possui autodetecção de ambiente, e se executarmos o exemplo em um servidor ativo, o erro será registrado em vez de exibido, e o visitante verá apenas uma mensagem amigável ao usuário:

O modo de produção suprime a exibição de todas as informações de depuração que enviamos usando dump(), e, claro, 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 é de desenvolvimento se a aplicação for executada no localhost (ou seja, endereço IP 127.0.0.1 ou ::1) e não houver proxy presente (ou seja, seu cabeçalho HTTP). Caso contrário, ele roda em modo de produção.

Se quisermos habilitar o modo de desenvolvimento em outros casos, por exemplo, para programadores acessando de um endereço IP específico, nós o fornecemos como um parâmetro para o método enable():

Debugger::enable('23.75.345.200'); // também pode ser fornecido um array de endereços IP

Recomendamos fortemente combinar o endereço IP com um cookie. Armazenamos um token secreto, por exemplo, secret1234, no cookie tracy-debug, e desta forma ativamos o modo de desenvolvimento apenas para programadores acessando de um endereço IP específico que possuem o token mencionado no cookie:

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

Também podemos 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ê estiver usando o Nette Framework, veja como definir o modo para ele, e ele será subsequentemente usado para o Tracy também.

Registro de erros

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

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

O registro de erros é extremamente útil. Imagine que todos os usuários da sua aplicação são, na verdade, testadores beta que fazem um trabalho de primeira linha encontrando erros gratuitamente, e seria tolice jogar fora seus valiosos relatórios na lixeira sem notá-los.

Se precisarmos registrar uma mensagem personalizada ou uma exceção que capturamos, usamos o método log():

Debugger::log('Ocorreu um erro inesperado'); // mensagem de texto

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

Se você quiser que o Tracy registre erros PHP como E_NOTICE ou E_WARNING com informações detalhadas (relatório HTML), defina Debugger::$logSeverity:

Debugger::$logSeverity = E_NOTICE | E_WARNING;

Para um verdadeiro profissional, o log de erros é uma fonte chave de informação, e ele quer ser informado imediatamente sobre cada novo erro. O Tracy o ajuda nisso, pois pode informar sobre um novo registro no log por e-mail. Determinamos para onde enviar os e-mails usando a variável $email:

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

Se você estiver usando o Nette Framework completo, isso e outras configurações podem ser definidas no arquivo de configuração.

No entanto, para evitar inundar sua caixa de entrada de e-mail, ele sempre envia apenas uma mensagem e cria o arquivo email-sent. Após receber a notificação por e-mail, o desenvolvedor verifica o log, corrige a aplicação e exclui o arquivo de monitoramento, reativando assim o envio de e-mails.

Abrindo no editor

Ao visualizar a página de erro, você pode clicar nos nomes dos arquivos, e eles serão abertos em seu editor com o cursor na linha apropriada. Também é possível criar arquivos (ação create file) ou corrigir erros neles (ação fix it). Para que isso funcione, basta 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 à última versão de patch.

Portas

Esta é uma lista de portas não oficiais para outros frameworks e CMS: