PT
RU
EN
ES
ZH
FR
DE
AR
HI
«Tela branca da morte» em PHP: como fazer os erros falarem?
Todo desenvolvedor PHP já passou por esta situação: o código parece funcionar, mas na tela — vazio. Nenhuma mensagem, nenhum aviso. Apenas uma tela branca e uma sensação de leve loucura. Familiar? Este é o clássico «Tela branca da morte» (White Screen of Death — WSOD). Na maioria das vezes, o problema é que a exibição de erros PHP está desativada.
No Stack Overflow, a pergunta «How do I get PHP errors to display?» acumulou milhares de visualizações. E não é por acaso: configurar a exibição de erros é o básico que todo desenvolvedor precisa saber. Mas simplesmente ativar o display_errors não é suficiente. É preciso entender como isso afeta o desempenho e a segurança da sua aplicação.
Neste artigo, vamos abordar:
- Como ativar erros PHP em diferentes ambientes (local, servidor, frameworks);
- Como configurar o
error_reportingpara uma depuração ideal; - Por que exibir erros em produção é uma má ideia;
- Como registrar erros sem perder desempenho.
Vamos nessa!
Por que o PHP não mostra erros? Três principais razões
Antes de mexer no código, vamos entender por que os erros podem estar ocultos. PHP é uma linguagem flexível, e seu comportamento depende das configurações do php.ini, do próprio script e do ambiente do servidor.
1. Configurações do php.ini
O principal culpado é a diretiva display_errors. Por padrão, em muitas hospedagens, ela está definida como Off. Isso é feito por segurança: em produção, mostrar o stack trace ao usuário é uma má prática.
2. Função error_reporting()
Mesmo que o display_errors esteja ativado, o nível de erros pode ser muito baixo. Por exemplo, error_reporting(0) ocultará tudo. Ou você pode filtrar acidentalmente os tipos de erro necessários (E_NOTICE, E_WARNING).
3. Erros antes da execução do script
Os mais traiçoeiros são os erros de sintaxe no php.ini ou em arquivos incluídos. Se o PHP não consegue nem iniciar o script, ele não chegará às suas configurações. Nesses casos, a verificação de sintaxe pelo console ajuda: php -l file.php.
Como ativar a exibição de erros PHP: guia passo a passo
Método 1. Editando o php.ini (configurações permanentes)
A maneira mais confiável é alterar o php.ini. Encontre o arquivo (geralmente em /etc/php/ ou /usr/local/etc/php/) e defina:
display_errors = Onerror_reporting = E_ALLApós as alterações, reinicie o servidor:
sudo service apache2 restart# ou para nginx + php-fpm:sudo service php8.1-fpm restartVantagens: a configuração vale para todos os scripts do servidor.
Desvantagens: requer acesso ao servidor; não é adequado para hospedagem compartilhada.
Método 2. Via .htaccess (para Apache)
Se você não tem acesso ao php.ini, mas tem Apache, use o .htaccess:
php_flag display_errors onphp_value error_reporting 32767 # E_ALLImportante: este método funciona se a diretiva AllowOverride estiver habilitada no servidor.
Método 3. Diretamente no script (para depuração)
A opção mais flexível é ativar erros em um arquivo específico. Ideal para desenvolvimento:
<?phpini_set('display_errors', 1);ini_set('display_startup_errors', 1);error_reporting(E_ALL);
// Seu códigoecho $undefined_variable; // Gera um Notice?>Observe o display_startup_errors — ele captura erros que ocorrem antes da execução do script (por exemplo, ao incluir arquivos).
Método 4. Especificidades de frameworks (Laravel, Symfony, WordPress)
Frameworks modernos têm seus próprios mecanismos. No Laravel
Blogs
Book Recommendations
Leia também
Conteinerização de aplicações C++ com Docker: guia completo
