Depuração de PHP: técnicas e ferramentas profissionais

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

Todo desenvolvedor PHP já enfrentou a temida tela branca da morte, o inexplicável 500 Internal Server Error ou uma variável que "estava funcionando há pouco". Nesses momentos, dá vontade de jogar o notebook pela janela. Mas, em vez disso, vamos transformar a depuração de código PHP em uma rotina que não cause arrepios.

Neste artigo, vamos explorar técnicas e ferramentas que ajudam você a encontrar bugs mais rápido do que a água ferve. Do clássico var_dump() à configuração avançada do Xdebug — tudo com exemplos práticos e casos reais. Vamos nessa!

1. Depuração básica: de var_dump() a error_reporting

1.1. var_dump() e print_r() — métodos antigos, mas eficazes

A maneira mais simples de depurar código PHP é exibir o conteúdo de uma variável na tela. Sim, não é elegante, mas quando você precisa entender rapidamente o que há em um array, o var_dump() faz o trabalho 100%.

<?php\n$users = [\n    ['name' => 'João', 'age' => 25],\n    ['name' => 'Maria', 'age' => 30]\n];\n\n// var_dump mostra os tipos de dados e a estrutura\nvar_dump($users);\n\n// print_r — uma versão mais compacta\necho '<pre>';\nprint_r($users);\necho '</pre>';\n?>

Dica: Use <pre> ao redor da saída para preservar a formatação. E nunca se esqueça de remover essas linhas de depuração antes de enviar para produção — senão os usuários verão seus "esqueletos no armário".

1.2. Ativando a exibição de todos os erros

A configuração padrão do PHP geralmente esconde os erros "debaixo do tapete". Para vê-los, adicione no início do script:

<?php\n// Mostrar todos os erros, incluindo notices e warnings\nerror_reporting(E_ALL);\nini_set('display_errors', 1);\n?>

Isso é especialmente útil ao depurar código PHP em um servidor local. Mas em produção, desative o display_errors — é uma questão de segurança!

1.3. debug_backtrace() — quem chamou esta função?

Às vezes, uma função é chamada de um lugar inesperado. O rastreamento da pilha de chamadas ajuda a encontrar a origem:

<?php\nfunction logError($message) {\n    $trace = debug_backtrace();\n    echo "Erro no arquivo: {$trace[0]['file']} na linha {$trace[0]['line']}<br>";\n    echo "Mensagem: $message";\n}\n\n// Agora qualquer chamada a logError mostrará de onde veio\nlogError('Algo deu errado');\n?>

2. Xdebug — o canivete suíço da depuração PHP

2.1. Instalação e configuração do Xdebug

Xdebug é uma extensão PHP que transforma a depuração em uma nave espacial. Com ele, você pode definir pontos de interrupção, inspecionar variáveis em tempo real e até fazer profiling do código.

Instalação via pecl (para Linux/Mac):

pecl install xdebug

Para Windows, baixe o .dll do site oficial e adicione no php.ini:

zend_extension = /caminho/para/xdebug.so\nxdebug.mode = debug\nxdebug.start_with_request = yes

2.2. Pontos de interrupção na IDE

Se você usa PhpStorm ou VS Code, configure a integração com Xdebug. Defina um ponto de interrupção (círculo vermelho à esquerda da linha de código), inicie a depuração — e o código para naquela linha. Você vê todas as variáveis, pode executar passo a passo e até alterar valores "em tempo real".

Exemplo: Você está procurando por que o total do pedido está errado. Coloque um ponto de interrupção na linha do cálculo, execute a requisição — e veja que $discount é null em vez de um número. Problema resolvido em 10 segundos!

2.3. Profiling com Xdebug

Código lento? Ative o profiler:

xdebug.mode = profile\nxdebug.output_dir = /tmp/profiles

Após executar o script, você obtém