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