Começando com Tracy

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

Ativar Tracy é fácil. Basta adicionar estas duas linhas de código, de preferência logo após o carregamento da biblioteca (como require 'vendor/autoload.php') e antes que qualquer saída seja enviada para o navegador:

use Tracy\Debugger;

Debugger::enable();

A primeira coisa que você vai notar no site é um Tracy Bar.

(Se você não vê nada, isso significa que Tracy está funcionando no modo de produção. Por razões de segurança, Tracy é visível apenas no local de produção. Você pode forçar Tracy a funcionar em modo de desenvolvimento passando o Debugger::Development como primeiro parâmetro do método enable() ).

O enable() envolve a mudança do nível de relatório de erros para E_ALL.

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

A fim de detectar erros de ortografia ao atribuir a um objeto, usamos o traço Nette\SmartObject.

Modo de produção e registro de erros

Como você pode ver, Tracy é bastante eloquente. É apreciada em um ambiente de desenvolvimento, mas em um servidor de produção, ela causaria um desastre. Qualquer informação de depuração não pode ser listada ali. Portanto, Tracy tem um ambiente com autodetecção e funcionalidade de registro. Ao invés de se mostrar, Tracy armazena informações em um arquivo de log e mostra ao visitante uma mensagem de erro do servidor compreensível para o usuário:

O modo de saída de produção suprime todas as informações de depuração que são enviadas via dump() e, é claro, todas as mensagens de erro geradas pelo PHP. Portanto, mesmo que você esqueça dump($obj) no código fonte, você não precisa se preocupar com isso em seu servidor de produção. Nada será visto.

O modo de saída é definido pelo primeiro parâmetro do Debugger::enable(). Você pode especificar uma constante Debugger::Production ou Debugger::Development. Outra opção é configurá-la de forma que o modo de desenvolvimento esteja ativado quando a aplicação for acessada a partir de um endereço IP definido com um valor definido de tracy-debug cookie. A sintaxe utilizada para conseguir isto é cookie-value@ip-address.

Se não for especificado, é usado o valor padrão Debugger::Detect. Neste caso, o sistema detecta um servidor por endereço IP. O modo de produção é escolhido se uma aplicação for acessada através de um endereço IP público. Um endereço IP local leva ao modo de desenvolvimento. Não é necessário definir o modo na maioria dos casos. O modo é reconhecido corretamente quando você está lançando a aplicação em seu servidor local ou em produção.

No modo de produção, Tracy captura automaticamente todos os erros e exceções em um log de texto. A menos que você especifique o contrário, ele será armazenado em log/error.log. Este log de erros é extremamente útil. Imagine, que todos os usuários de sua aplicação são na verdade betatesters. Eles estão fazendo trabalho de ponta gratuitamente ao caçar bugs e você seria tolo se você jogasse fora seus valiosos relatórios em um cesto de reciclagem sem ser notado.

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
}

Um diretório para registro de erros pode ser definido pelo segundo parâmetro do método enable():

Debugger::enable(Debugger::Detect, __DIR__ . '/mylog');

Se você quiser que 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 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

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