Como exibir erros no PHP?
Para exibir os erros gerados durante a execução de um script PHP, é possível ativar a diretiva display_errors e definir E_ALL como nível de relatório. As configurações devem ser adicionadas no início do arquivo responsável por iniciar a aplicação:
<?php
ini_set('display_errors', '1');
error_reporting(E_ALL);
Nesse exemplo, display_errors permite que as mensagens sejam incluídas na saída da aplicação, enquanto error_reporting(E_ALL) determina que todos os níveis de erro reconhecidos pela versão atual do PHP devem ser reportados.
Essa configuração só começa a funcionar depois que o arquivo é carregado e executado. Portanto, ela não consegue exibir um erro de sintaxe presente no próprio arquivo nem uma falha ocorrida durante a inicialização do PHP.
Para diagnosticar erros de inicialização, a diretiva display_startup_errors deve ser definida previamente no php.ini ou em outra configuração carregada antes do processo do PHP começar.
A exibição de erros deve ser usada somente em ambientes controlados, como desenvolvimento local, homologação restrita ou uma aplicação acessível apenas pelo time de programadores.
Como ativar a exibição de erros pelo código?
A configuração pelo próprio código é útil quando não existe acesso direto ao arquivo php.ini ou quando a exibição precisa ser ativada temporariamente em uma aplicação específica.
As instruções devem aparecer o mais cedo possível no fluxo de execução, preferencialmente no arquivo de entrada da aplicação, como index.php, bootstrap.php ou outro arquivo carregado antes dos demais componentes.
Ainda assim, essa estratégia só consegue mostrar erros ocorridos depois que as instruções foram executadas.
Usando display_errors
A diretiva display_errors controla se as mensagens geradas pelo PHP serão enviadas para a saída da aplicação. Ela pode ser ativada em tempo de execução com a função ini_set():
<?php
ini_set('display_errors', '1');
O primeiro argumento informa qual diretiva será alterada. O segundo define o novo valor, sendo '1' equivalente à configuração ativada.
Também é possível consultar o valor utilizado no momento:
<?php
var_dump(ini_get('display_errors'));
Esse teste ajuda a verificar se a configuração foi realmente aplicada. Servidores gerenciados, containers, frameworks ou configurações do PHP-FPM podem interferir no comportamento esperado.
É importante lembrar que display_errors define se a mensagem será apresentada, mas não determina sozinho quais tipos de erro serão reportados. Para isso, é necessário configurar o nível de error_reporting.
Configurando error_reporting
A função error_reporting() define quais níveis de erro o PHP deve considerar. Durante o desenvolvimento, o mais indicado é utilizar a constante E_ALL:
<?php
error_reporting(E_ALL);
Essa configuração inclui erros fatais, warnings, notices, mensagens de depreciação e outras categorias reconhecidas pelo PHP.
Também é possível combinar constantes para ocultar categorias específicas:
<?php
error_reporting(E_ALL & ~E_DEPRECATED);
Nesse caso, todos os erros são reportados, exceto os classificados como E_DEPRECATED. Embora esse ajuste possa ser necessário temporariamente em sistemas legados, ignorar avisos de depreciação por muito tempo dificulta futuras atualizações da aplicação.
Para descobrir qual nível está configurado no momento, basta chamar a função sem argumentos:
<?php
$currentLevel = error_reporting();
var_dump($currentLevel);
Como exibir todos os erros do PHP?
A combinação mais comum para exibir os erros gerados durante a execução de uma aplicação é:
<?php
ini_set('display_errors', '1');
error_reporting(E_ALL);
Para testar se a configuração está funcionando, pode ser gerado um erro proposital em um ambiente local:
<?php
ini_set('display_errors', '1');
error_reporting(E_ALL);
echo $variavelNaoDefinida;
O PHP deverá apresentar uma mensagem informando que a variável não foi definida, além do arquivo e da linha em que o problema ocorreu.
Outro teste possível é chamar uma função inexistente:
<?php
ini_set('display_errors', '1');
error_reporting(E_ALL);
funcaoInexistente();
Nesse caso, a execução será interrompida por um erro fatal. Dependendo da configuração do ambiente, também poderá ser exibido um stack trace com a sequência de chamadas que levou à falha.
Frameworks e sistemas de gerenciamento de conteúdo podem capturar erros e exceções por meio de manipuladores próprios. Por isso, uma aplicação pode continuar mostrando uma página personalizada mesmo com display_errors ativado.
Erros de inicialização, carregamento de extensões ou configuração do próprio PHP devem ser tratados separadamente, por meio do php.ini e dos logs do servidor.
Como ativar erros pelo arquivo php.ini?
O arquivo php.ini contém as principais configurações do PHP. Alterá-lo é uma opção mais abrangente do que inserir as diretivas em cada arquivo da aplicação.
Para configurar um ambiente de desenvolvimento, procure pelas diretivas relacionadas a erros e utilize valores semelhantes aos seguintes:
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
Nesse caso, display_startup_errors é carregado antes da execução dos scripts e pode ajudar a identificar problemas ocorridos durante a inicialização do PHP.
Também é possível definir um arquivo específico para os registros:
error_log = /var/log/php/error.log
O diretório precisa existir e permitir que o processo responsável pelo PHP grave informações no arquivo. Caso contrário, os erros podem não ser registrados mesmo com log_errors ativado.
Para descobrir qual arquivo de configuração é usado pelo PHP no terminal, execute:
php --ini
Esse comando mostra a configuração da interface de linha de comando, conhecida como CLI. Ela não é necessariamente a mesma utilizada pelas páginas acessadas pelo navegador.
Em uma página qualquer, a informação pode ser consultada temporariamente com:
<?php
phpinfo();
Ao acessá-la, procure pelo campo Loaded Configuration File. Depois do diagnóstico, remova o arquivo com phpinfo(), pois ele revela diversas informações sobre o servidor.
O PHP executado no terminal pode carregar um php.ini diferente daquele utilizado pelo Apache, Nginx ou PHP-FPM. Esse é um motivo comum para uma configuração funcionar na linha de comando, mas não produzir o mesmo resultado no navegador.
Depois de alterar o arquivo, pode ser necessário reiniciar o serviço correspondente. Em um servidor com PHP-FPM, por exemplo, o comando pode seguir este formato:
sudo systemctl restart php-fpm
O nome exato do serviço varia conforme o sistema operacional, a versão instalada e a forma como o PHP foi configurado.
Qual é a diferença entre exibir e registrar erros?
Exibir e registrar são comportamentos independentes. Uma aplicação pode mostrar erros no navegador, gravá-los em um arquivo, realizar as duas ações ou não fazer nenhuma delas.
display_errors
A diretiva display_errors controla a inclusão das mensagens na resposta gerada pelo PHP. Em uma página HTML, o erro normalmente aparece no próprio navegador. Em uma API, a mensagem pode ser misturada ao JSON ou a outro formato retornado.
Essa exibição imediata é útil durante o desenvolvimento, pois permite visualizar rapidamente o tipo de erro, o arquivo afetado e a linha correspondente.
Por outro lado, uma mensagem pode revelar caminhos internos do servidor, nomes de classes, consultas ao banco de dados, detalhes da arquitetura e partes do stack trace. Por esse motivo, essa diretiva deve permanecer desativada em produção.
log_errors
A diretiva log_errors permite registrar as mensagens sem mostrá-las no front:
log_errors = On
display_errors = Off
error_reporting = E_ALL
Essa é a combinação mais adequada para produção: os erros continuam sendo identificados e registrados, mas a resposta pública não revela os detalhes técnicos.
O destino pode ser definido pela diretiva error_log:
error_log = /var/log/php/error.log
Também é possível enviar uma mensagem personalizada para o sistema de logs usando a função error_log():
<?php
error_log('Falha ao processar o pedido de número 1234');
Logs bem configurados ajudam a investigar problemas que não podem ser reproduzidos localmente. No entanto, eles precisam de controle de acesso, monitoramento de espaço em disco e rotação periódica para não crescerem indefinidamente.
Por que os erros do PHP não aparecem?
Quando o PHP continua exibindo apenas uma tela em branco ou uma resposta genérica, o problema pode estar na configuração do ambiente, na aplicação ou no momento em que a falha acontece. Os motivos mais comuns são:
display_errors está desativado: o PHP identifica o erro, mas não inclui a mensagem na resposta.- O nível de
error_reporting é limitado: a categoria do erro ocorrido pode estar sendo ignorada pela configuração atual. - O
php.ini alterado não é o correto: a interface de linha de comando, o servidor web e o PHP-FPM podem usar arquivos diferentes. - O serviço não foi reiniciado: algumas alterações no
php.ini só entram em vigor depois que o processo do PHP ou o servidor web é recarregado. - Existe um erro de sintaxe no arquivo inicial: como o PHP não consegue compilar o arquivo, as chamadas a
ini_set() presentes nele não chegam a ser executadas. - A falha ocorreu durante a inicialização: erros anteriores à execução do script precisam ser investigados pela configuração global e pelos logs do servidor.
- O framework captura a exceção: aplicações modernas normalmente possuem manipuladores que substituem a mensagem padrão por uma página de erro.
- O modo de depuração do framework está desativado: configurações como debug mode podem controlar a apresentação dos detalhes independentemente de
display_errors. - O erro está sendo enviado para um log: a aplicação pode estar configurada para registrar a falha sem mostrá-la na tela.
- O log não possui permissão de escrita: o processo do PHP pode não conseguir criar ou modificar o arquivo configurado.
- A resposta foi alterada pelo servidor: proxies, servidores pré-configurados e plataformas de hospedagem podem substituir a saída por uma página genérica de erro 500.
Quando a configuração pelo código não funciona, o primeiro passo é consultar os logs do servidor. Em seguida, vale confirmar o php.ini carregado, o nível retornado por error_reporting() e o valor de ini_get('display_errors').
Em projetos com um arquivo de entrada central, também pode ser útil colocar as configurações de diagnóstico nesse arquivo e carregar o restante da aplicação posteriormente:
<?php
ini_set('display_errors', '1');
error_reporting(E_ALL);
require __DIR__ . '/app.php';
Assim, erros ocorridos durante o carregamento de app.php podem ser exibidos. A estratégia não resolve um erro de sintaxe presente no próprio arquivo que contém as configurações.
É seguro exibir erros em produção?
Não é seguro deixar display_errors ativado em produção. Mensagens de erro podem revelar caminhos absolutos do servidor, versões de componentes, consultas SQL, parâmetros recebidos, nomes de arquivos e detalhes da lógica interna da aplicação.
Uma configuração mais adequada para produção é:
display_errors = Off
display_startup_errors = Off
log_errors = On
error_reporting = E_ALL
error_log = /var/log/php/error.log
Manter error_reporting = E_ALL não significa que os visitantes verão todos os erros. Essa diretiva define o que deve ser reportado, enquanto display_errors = Off impede que os detalhes sejam enviados na resposta pública.
Além das configurações do PHP, o modo de depuração de frameworks e sistemas de gerenciamento de conteúdo também deve permanecer desativado em produção.
A aplicação deve apresentar ao usuário uma mensagem genérica, registrar os detalhes internamente e permitir que a equipe investigue o problema pelos logs. Em sistemas mais estruturados, os registros também podem ser enviados para uma ferramenta de monitoramento e observabilidade.
Informações sensíveis não devem ser gravadas indiscriminadamente. Senhas, tokens de acesso, números completos de cartão e outros dados protegidos precisam ser removidos ou mascarados antes de entrarem nos logs.
Conclusão
Para mostrar erros gerados durante a execução de um script PHP, a configuração mais básica combina ini_set('display_errors', '1') e error_reporting(E_ALL). Quando o ajuste precisa valer para todo o ambiente ou abranger falhas de inicialização, o ideal é alterar o php.ini e reiniciar o processo em andamento.
Em produção, a lógica deve ser invertida: os erros precisam continuar sendo reportados e registrados, mas nunca expostos diretamente aos usuários.
