Depuração de código PHP: técnicas e ferramentas para profissionais

Introdução: Por que a depuração é um superpoder do desenvolvedor

Você já ficou sentado à noite, olhando para o monitor, sem conseguir entender por que seu site PHP exibia a tela branca da morte? Ou, pior ainda, números incorretos em um relatório? Parabéns, você se deparou com a depuração. Muitos iniciantes temem essa palavra, achando que depurar código PHP é coisa de gurus selecionados. Na verdade, é apenas uma habilidade que pode e deve ser treinada.

Neste artigo, não vamos apenas listar funções. Vamos analisar cenários reais: desde o simples var_dump() até a configuração do Xdebug na IDE. Você aprenderá como transformar o processo de busca de erros em uma rotina estruturada, e não em um palpite no escuro. Vamos lá!

1. Clássico do gênero: var_dump e print_r

A maneira mais simples de depurar PHP é inserir var_dump($variable) em um local suspeito. Mas há um detalhe: nem todos fazem isso corretamente.

O var_dump correto

Muitos escrevem assim:

var_dump($user);

E obtêm uma bagunça na tela. É melhor formatar a saída:

echo '<pre>';\nvar_dump($user);\necho '</pre>';\ndie(); // interrompe a execução para não atrapalhar o restante da saída

E para arrays e objetos, é mais conveniente usar print_r() com a flag true para salvar o resultado em uma string:

$data = print_r($users, true);\nfile_put_contents('debug.log', $data, FILE_APPEND);

Dica: Nunca deixe var_dump em produção. Use depuração condicional:

if (defined('DEBUG_MODE') && DEBUG_MODE) {\n    var_dump($variable);\n}

2. Log: seu melhor amigo em produção

Quando o site já está no servidor, você não pode simplesmente exibir o erro na tela. É aí que entra o log PHP. A função embutida error_log() é a base.

Como configurar o error_log

No arquivo php.ini, especifique:

error_reporting = E_ALL\ndisplay_errors = Off\nlog_errors = On\nerror_log = /var/log/php_errors.log

Agora, todos os erros, incluindo avisos, serão gravados no arquivo. E no código, você pode fazer assim:

if ($result === false) {\n    error_log("Erro na consulta ao BD: " . $db->error, 3, '/var/log/myapp.log');\n    // 3 — significa gravação em arquivo, não no syslog\n}

Abordagem moderna: Monolog

Para projetos sérios, use a biblioteca Monolog. Ela pode gravar em arquivos, no Slack, no banco de dados e até no Telegram. Exemplo de configuração:

use Monolog\\Logger;\nuse Monolog\\Handler\\StreamHandler;\n\n$log = new Logger('my_app');\n$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Logger::WARNING));\n$log->warning('Usuário tentou acessar sem permissão', ['user_id' => 123]);

3. Xdebug: motor reativo de depuração

Se você ainda não instalou o Xdebug, está perdendo tempo. Não é apenas uma ferramenta — é um foguete para o desenvolvedor. Ele permite definir pontos de parada (breakpoints), visualizar valores de variáveis em tempo real e até perfilar o código.

Instalação e configuração

Instale via gerenciador de pacotes:

pecl install xdebug\n# ou para Ubuntu:\nsudo apt install php-xdebug

Adicione no php.ini:

zend_extension=xdebug.so\nxdebug.mode=debug\nxdebug.start_with_request=yes\nxdebug.client_host=127.0.0.1\nxdebug.client_port=9003

Agora configure sua IDE. No PhpStorm, isso é feito em dois cliques: configure o interpretador PHP e clique em "Start Listening for PHP Debug Connections".

Como funciona na prática

Defina um ponto de parada (círculo vermelho) na linha com o código suspeito. Execute o script no navegador com o parâmetro ?XDEBUG_SESSION_START=1.