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:
- Drupal 7
- Laravel framework: recca0120/laravel-tracy, whipsterCZ/laravel-tracy
- OpenCart
- ProcessWire CMS/CMF
- Slim Framework
- Symfony framework: kutny/tracy-bundle, VasekPurchart/Tracy-Blue-Screen-Bundle
- Wordpress