Como fazer o PHP mostrar todos os erros: guia completo

«O PHP mostra uma tela branca, e eu preciso de erros!» — situação familiar?

Você escreve código em PHP, executa o script, e em vez de um resultado — vazio. Ou, pior ainda, algum erro estranho sem a menor pista sobre a causa. Familiar? Se você já se perguntou «How can I get useful error messages in PHP?» — você não está sozinho. Esta pergunta no Stack Overflow acumulou milhares de visualizações, e não é à toa. O PHP por padrão é configurado para ocultar erros em servidores de produção, mas na fase de desenvolvimento isso se torna uma verdadeira dor de cabeça.

Neste artigo, vamos abordar todas as formas de fazer o PHP falar com você em uma linguagem compreensível. Você aprenderá como ativar a exibição de erros, configurar o nível de detalhamento e registrá-los, para que a depuração deixe de ser um jogo de adivinhação. Vamos lá!

Por que o PHP fica em silêncio? A raiz do problema — as configurações do servidor

Antes de aprendermos a obter mensagens úteis, vamos entender por que elas não aparecem. O PHP é uma linguagem com uma filosofia rigorosa de segurança. Em servidores de produção, mostrar erros aos usuários é má prática e uma ameaça à segurança. Por isso, no php.ini (arquivo de configuração principal do PHP), as configurações padrão são:

• display_errors = Off — erros não são exibidos na tela.
• error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT — não exibe todos os tipos de erros.

Mas para o desenvolvimento local, isso é um desastre. Como corrigir? Existem três caminhos principais.

Método 1: Alterar o php.ini (se tiver acesso)

A maneira mais confiável é editar o arquivo php.ini. Encontre-o (geralmente está na raiz da instalação do PHP ou na pasta etc/ no Linux). Em seguida, localize e altere as seguintes linhas:

; Ativa a exibição de erros na teladisplay_errors = On

; Define o nível máximo de relatório (todos os erros, exceto avisos de obsoletismo)error_reporting = E_ALL

Após as alterações, reinicie o servidor web (Apache, Nginx ou o servidor PHP embutido), caso contrário, as configurações não serão aplicadas.

Importante: Em um servidor de produção, display_errors deve estar sempre Off. Use este método apenas para desenvolvimento.

Método 2: Usar .htaccess (para Apache)

Se você não tem acesso ao php.ini, mas usa Apache, pode sobrescrever as configurações através do arquivo .htaccess na raiz do seu site. Adicione a ele:

php_flag display_errors onphp_value error_reporting E_ALL

Isso funcionará se o Apache permitir a sobrescrita das diretivas do PHP (geralmente é o caso na maioria das hospedagens).

Método 3: Ativar erros diretamente no código (o mais flexível)

Este é o meu método favorito para depuração rápida. Você pode inserir estas linhas no início do script (logo após <?php):

<?php// Ativa o nível máximo de relatório de erroserror_reporting(E_ALL);

// Ativa a exibição de erros na telaini_set('display_errors', 1);

// Ativa a exibição de erros de inicialização (por exemplo, se o erro estiver no próprio ini_set)ini_set('display_startup_errors', 1);?>

Agora, qualquer Warning, Notice ou Fatal Error será exibido diretamente no navegador. Prático, não é?

Quais tipos de erros existem no PHP e o que significam?

Para ler os «sinais» do PHP, você precisa conhecer a linguagem deles. Aqui estão os principais tipos de erros que você verá com mais frequência:

• E_ERROR — erro fatal. O script é interrompido. Exemplo: chamada de uma função inexistente.
• E_WARNING — aviso. O script continua, mas algo deu errado. Exemplo: include() de um arquivo inexistente.
• E_NOTICE — notificação. Não é um erro, mas um problema potencial. Exemplo: uso de uma variável não definida.<