Display errors PHP: como exibir todos os erros do PHP

Quando um script PHP falha e a página aparece totalmente em branco, quase sempre o motivo é que a exibição de erros está desligada — o PHP encontrou o erro, mas foi configurado para não mostrá-lo. Para revelar a mensagem, é preciso ativar o display_errors. É a primeira coisa a fazer para depurar qualquer problema de PHP.

Por padrão, muitos servidores vêm com a exibição de erros desativada (o que é correto para um site no ar). Mas, ao desenvolver ou diagnosticar um problema, você precisa ver as mensagens. Este guia mostra como ativar a exibição de todos os erros do PHP pelos três caminhos possíveis — direto no código, no php.ini e no .htaccess —, como usar o error_reporting para escolher o que aparece, e por que é essencial desligar tudo isso quando o site voltar ao ar.

Por que o PHP não mostra os erros

Quando uma página PHP dá erro e aparece totalmente em branco (a famosa “tela branca da morte”), o que aconteceu foi o seguinte: o PHP executou o script, encontrou um erro fatal, interrompeu tudo — e, como estava configurado para não exibir erros, não mostrou nenhuma mensagem. O resultado é uma página vazia, sem pista nenhuma.

Isso é controlado por duas diretivas do php.ini que trabalham juntas:

• display_errors — decide se os erros aparecem na tela (On) ou não (Off).
• error_reporting — decide quais tipos de erro são considerados (erros fatais, avisos, notices, etc.).

Em um servidor de produção, o display_errors normalmente vem desligado de propósito, por segurança. Para desenvolver ou diagnosticar, você precisa ligá-lo temporariamente. Há três formas de fazer isso.

Caminho 1: direto no código PHP (ini_set)

A forma mais rápida e localizada, ideal para depurar um script específico, é adicionar estas linhas no início do arquivo PHP:

O que cada linha faz:

• ini_set('display_errors', 1) — liga a exibição de erros na tela para este script.
• ini_set('display_startup_errors', 1) — mostra também os erros que ocorrem na inicialização do próprio PHP (que o display_errors sozinho não pega).
• error_reporting(E_ALL) — pede que todos os níveis de erro sejam reportados: fatais, avisos (warnings), notices e o resto.

Há uma limitação importante: se o erro for de sintaxe no próprio arquivo onde você colocou essas linhas, elas não chegam a rodar — o PHP falha antes de executá-las. Nesse caso, use um dos outros dois caminhos, ou coloque o código de teste num arquivo separado que inclua o problemático.

Caminho 2: no php.ini

Para ligar a exibição de erros para todo o site (útil em um ambiente de desenvolvimento inteiro), ajuste as diretivas no php.ini:

Lembre-se de que, ao editar o php.ini diretamente, a mudança só vale depois de reiniciar o servidor web (Apache) ou o PHP-FPM. Em hospedagem compartilhada, você faz esse ajuste pelo painel — no cPanel, em Select PHP Version → Options, localizando display_errors e error_reporting. O guia do php.ini detalha cada forma de editar.

Caminho 3: no .htaccess

Se você usa servidor Apache e não tem acesso ao php.ini, pode ligar a exibição pelo .htaccess, na raiz do site:

Esse caminho é prático porque vale para todo o site sem precisar reiniciar nada, mas depende de o servidor ser Apache e de permitir diretivas php_value/php_flag no .htaccess (o que não acontece em setups com PHP-FPM). Se as linhas gerarem um erro 500, é sinal de que o servidor não aceita esse método — use então o php.ini ou o painel.

Entendendo o error_reporting

O error_reporting é o que define quais erros você quer ver. O valor mais usado para depurar é o E_ALL, que mostra tudo, mas há outros níveis úteis:

Para depurar, E_ALL é o recomendado — você quer ver tudo, inclusive os notices, que muitas vezes apontam a origem de um bug (como uma variável não definida). O display_errors liga a exibição; o error_reporting filtra o que é exibido. Os dois precisam estar configurados para você ver o erro.

Ver erros sem exibi-los na tela: o log

Nem sempre você quer os erros aparecendo na tela — especialmente num site que tem visitantes. A alternativa é registrar os erros em um arquivo de log, em vez de exibi-los:

Assim, os erros não aparecem para os visitantes, mas ficam gravados num arquivo que só você acessa. É o método ideal para produção: você continua sabendo o que deu errado (consultando o log), sem expor nada ao público. Muitos painéis de hospedagem já mantêm um arquivo de log de erros do PHP que você pode consultar sem configurar nada.

Por que desligar em produção

A regra de ouro: display_errors ligado no desenvolvimento, desligado na produção. Ao terminar de depurar um problema num site que está no ar, lembre-se de remover as linhas de ini_set que você adicionou, ou de desligar a diretiva no painel. Deixá-la ligada é um dos deslizes de segurança mais comuns em PHP.

Erros ainda não aparecem? Verifique

Se você ativou tudo e a página continua em branco, alguns pontos a checar:

• Erro de sintaxe no arquivo: se o próprio arquivo tem um erro de sintaxe, o ini_set dentro dele não roda. Ative pelo php.ini ou .htaccess, ou verifique o log de erros.
• A configuração não foi aplicada: se editou o php.ini, confirme que reiniciou o serviço e que editou o arquivo certo (veja como no guia do php.ini).
• O erro está sendo logado, não exibido: consulte o arquivo de log de erros do PHP (o painel da hospedagem costuma ter um “Error Log”).
• Cache de página: se o site usa cache, limpe-o para garantir que está vendo a execução real do PHP.

Perguntas frequentes

Como exibir todos os erros no PHP?
Adicione ao início do seu script as linhas ini_set('display_errors', 1);, ini_set('display_startup_errors', 1); e error_reporting(E_ALL);. A primeira liga a exibição na tela, a segunda inclui erros de inicialização e a terceira faz com que todos os tipos de erro sejam reportados. Para todo o site, ajuste as mesmas diretivas no php.ini ou no .htaccess.

Por que meu PHP não mostra erros e a tela fica em branco?
Porque a diretiva display_errors está desligada. Quando o PHP encontra um erro fatal e a exibição está desativada, ele interrompe o script e devolve uma página vazia, sem mensagem. Ativando o display_errors e o error_reporting(E_ALL), a mensagem de erro passa a aparecer, revelando a causa do problema.

Qual a diferença entre display_errors e error_reporting?
São complementares. O display_errors decide se os erros aparecem na tela ou não (On/Off). O error_reporting decide quais tipos de erro são considerados (fatais, avisos, notices). Para ver um erro, os dois precisam estar configurados: a exibição ligada e o nível incluindo aquele tipo de erro. O valor error_reporting(E_ALL) mostra todos.

Como exibir erros do PHP sem acesso ao php.ini?
Você tem dois caminhos. No próprio código, adicione ini_set('display_errors', 1) e error_reporting(E_ALL) no início do script. No Apache, pode usar o arquivo .htaccess com php_flag display_errors on e php_value error_reporting E_ALL. Em hospedagem compartilhada, também dá para ajustar pelo painel, no cPanel em Select PHP Version.

É seguro deixar a exibição de erros ligada?
Não em produção. As mensagens de erro expõem caminhos de arquivos, nomes de banco de dados e outros detalhes que ajudam um atacante. Em um site no ar, mantenha display_errors = Off e registre os erros num log (log_errors = On) para acompanhá-los com segurança. A exibição na tela deve ficar ligada apenas em ambiente de desenvolvimento.

Onde ficam os logs de erro do PHP?
O local é definido pela diretiva error_log no php.ini. Em muitas hospedagens, há um arquivo de log de erros acessível pelo painel de controle (procure por “Error Log” no cPanel). Se você define o error_log manualmente, aponte para um caminho onde o PHP tenha permissão de escrita, e consulte esse arquivo para ver os erros registrados.

O que significa error_reporting(E_ALL)?
É o comando que diz ao PHP para reportar todos os níveis de erro: erros fatais, avisos (warnings), notices, avisos de código obsoleto (deprecated) e o resto. É o valor recomendado durante o desenvolvimento, porque mostra o quadro completo — inclusive os notices, que costumam apontar a origem de bugs sutis, como o uso de uma variável não definida.

Conclusão

Uma tela em branco no PHP quase nunca é um mistério — é só o erro escondido. Para revelá-lo, o essencial é: no código, ini_set('display_errors', 1) mais error_reporting(E_ALL) no topo do script; ou, para o site todo, as mesmas diretivas no php.ini ou no .htaccess. Lembre da divisão de papéis — o display_errors liga a exibição, o error_reporting escolhe o que aparece — e da regra de ouro: ligado só em desenvolvimento. Num site no ar, mantenha desligado e acompanhe pelo log de erros. Com a exibição ativada, o PHP deixa de esconder o problema e passa a te dizer exatamente onde ele está.