Como exibir erros PHP: ativar display_errors e otimizar o site

Introdução: Por que desenvolvedores temem a tela branca?

Todo desenvolvedor PHP já passou por isso: o código parece certo, mas em vez do resultado esperado, surge uma página em branco. Nenhum erro, nenhum aviso. Apenas silêncio e suor frio. Soa familiar?

No Stack Overflow, a pergunta “How do I get PHP errors to display?” acumulou milhares de visualizações e centenas de respostas. Não é por acaso: saber ativar e tratar erros corretamente é uma habilidade essencial que economiza horas de depuração. Mas há um detalhe: uma configuração inadequada pode não apenas não ajudar, mas também reduzir a performance do seu site ou, pior ainda, expor vulnerabilidades.

Neste artigo, vamos explorar todas as formas de ativar a exibição de erros PHP — desde soluções rápidas para desenvolvimento local até configurações seguras para servidores de produção. E, claro, falaremos sobre otimização: como não sobrecarregar os logs e nem deixar o site lento.

Breve introdução: quais são os tipos de erros PHP?

Antes de ativar a exibição, é útil entender com o que estamos lidando. O PHP gera vários níveis de erros:

\n
• E_ERROR — erro fatal. O script é interrompido. Exemplo: falta de memória, chamada de classe inexistente.
\n
• E_WARNING — não fatal. O script continua, mas algo deu errado. Exemplo: include de um arquivo que não existe.
\n
• E_NOTICE — aviso. Geralmente sobre problemas menores (variável não definida).
\n
• E_PARSE — erro de sintaxe. Ocorre antes da execução do código, difícil de capturar em tempo de execução.
\n
• E_ALL — inclui todos os níveis, exceto E_STRICT (antes do PHP 8.0).
\n

Lembre-se: durante o desenvolvimento, queremos ver todos os erros. No servidor de produção, apenas os críticos, e mesmo assim apenas nos logs, não na tela.

Método nº1: Rápido e direto — diretamente no código

O método mais simples para depuração pontual é inserir duas linhas mágicas no início do script:

<?php\nini_set('display_errors', 1);\nini_set('display_startup_errors', 1);\nerror_reporting(E_ALL);\n?>

O que está acontecendo aqui?

\n
• display_errors — ativa a exibição de erros na tela.
\n
• display_startup_errors — mostra erros que ocorrem durante a inicialização do PHP (por exemplo, no php.ini).
\n
• error_reporting(E_ALL) — define o nível de relatório: exibir tudo.
\n

Este método é ideal para um único arquivo que você está depurando. Mas tem desvantagens: você precisa lembrar de remover essas linhas antes de enviar para produção. Caso contrário, corre o risco de expor os “bastidores” da sua aplicação aos usuários.

Método nº2: Configuração do php.ini — global e permanente

Se você trabalha em uma máquina local ou controla o servidor, é mais fácil editar o php.ini. Localize este arquivo (geralmente em /etc/php/ ou /usr/local/etc/php/) e altere as seguintes diretivas:

display_errors = On\ndisplay_startup_errors = On\nerror_reporting = E_ALL

Após as alterações, não se esqueça de reiniciar o servidor web:

sudo systemctl restart apache2\n# ou\nsudo systemctl restart nginx php8.1-fpm

Importante: no servidor de produção, display_errors deve estar como Off. Em vez disso, configure o log de erros em um arquivo:

display_errors = Off\nlog_errors = On\nerror_log = /var/log/php_errors.log\nerror_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT

Isso reduz a carga na saída e protege os dados do site.

Método nº3: Via .htaccess — para hospedagem compartilhada

Se você não tem acesso ao php.ini (por exemplo, em uma hospedagem barata), use o arquivo .htaccess na raiz do site:

php_flag display_errors on\nphp_flag display_startup_errors on\nphp_value error_reporting 32767