error_reporting()

Introdução

Este capítulo aborda como o PHP relata erros: a função error_reporting() que controla quais erros o PHP gera, as diretivas display_errors e log_errors que controlam para onde esses erros vão, e as funções auxiliares usadas para tratá-los e registrá-los. Ao final, você saberá como configurar o relatório de erros de forma diferente para desenvolvimento e produção, e por que configurar isso incorretamente é um dos erros de segurança e depuração mais comuns em PHP.

Por que o relatório de erros é importante

O PHP é executado como uma linguagem dinâmica e tolerante: muitos erros que impediriam outra linguagem de compilar surgem em tempo de execução como avisos, notificações ou mensagens de depreciação. Se você os suprimir, comportamentos incorretos podem passar silenciosamente para a produção. Se você os exibir para os usuários finais, pode vazar caminhos de arquivos, SQL e rastreamentos de pilha para atacantes.

Um bom relatório de erros encontra o equilíbrio certo para cada ambiente:

• Em desenvolvimento — exiba tudo, de forma clara, para que você capture os bugs enquanto os escreve.
• Em produção — não exiba nada ao usuário, mas registre tudo em um arquivo para análise posterior.

Níveis de erro e constantes

Os erros do PHP são classificados por nível. Cada nível é uma constante predefinida, e você os combina com operadores bit a bit. Os níveis mais comuns:

Como essas são flags de bit, você as combina com | (incluir), & (máscara) e ~ (negar):

// All errors EXCEPT notices and deprecation messages
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);

// Only fatal errors and warnings
error_reporting(E_ERROR | E_WARNING);

Nota de versão: Desde o PHP 8.0, o nível padrão de error_reporting é E_ALL. O E_STRICT foi depreciado no 8.0 e removido no 8.4, e suas notificações agora fazem parte do E_ALL, portanto não é mais necessário adicioná-lo separadamente.

Relatório vs. exibição: duas configurações distintas

Uma fonte frequente de confusão é que duas chaves independentes determinam se você realmente vê um erro:

1. error_reporting() — decide quais níveis o PHP gera.
2. display_errors — decide se os erros gerados são impressos na saída.

Você precisa ativar ambos para ver um erro na tela. O exemplo abaixo gera uma notificação de nível E_ALL e a exibe porque ambas as chaves estão ativas:

<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');

echo $undefined;   // Warning: Undefined variable $undefined

Se display_errors estivesse desativado, a mesma notificação ainda seria gerada (e poderia ser registrada), mas nada apareceria na saída da página.

As principais funções de relatório de erros

error_reporting()

Define quais níveis de erro são reportados em tempo de execução e retorna o nível anterior. Chame sem argumento para ler a configuração atual.

<?php
$old = error_reporting(E_ALL & ~E_NOTICE);
echo "Now reporting all errors except notices.\n";
echo "Previous level was: " . $old . "\n";

ini_set()

Substitui uma diretiva do php.ini durante a execução do script atual. É o equivalente em tempo de execução de editar o php.ini, e é como você altera display_errors, display_startup_errors e log_errors a partir do código.

<?php
// Development setup: show everything on screen
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

Observação: display_errors não consegue capturar erros fatais de análise no mesmo arquivo, pois o arquivo inteiro falha na compilação antes que ini_set() seja executado. Para isso, defina a diretiva no próprio php.ini.

set_error_handler()

Registra um callback que é executado sempre que um erro (não fatal) é gerado, permitindo substituir o comportamento padrão do PHP — por exemplo, para converter avisos em exceções ou formatá-los como JSON para uma API. O callback recebe o nível de erro, a mensagem, o arquivo e a linha.

<?php
set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline): bool {
    echo "[$errno] $errstr in " . basename($errfile) . " on line $errline\n";
    return true; // true = we handled it; PHP's internal handler is skipped
});

echo $undefined; // routed to our handler instead of the default message

Veja set_error_handler() para a assinatura completa e como restaurar o handler anterior.

error_log() e trigger_error()

• error_log() envia uma mensagem para o log configurado do PHP, um arquivo específico ou um endereço de e-mail — nunca para a saída da página. Esta é a forma segura para produção de registrar problemas.
• trigger_error() gera um erro definido por você (níveis E_USER_*), que então passa pelo mesmo pipeline de error_reporting/handler que os erros internos.

<?php
// Append a message to a specific log file (message type 3)
error_log("Payment gateway timed out", 3, "/var/log/php_errors.log");

// Raise a user-level warning that your handler / log can pick up
trigger_error("Cache miss for product 42", E_USER_WARNING);

Saiba mais em error_log() e trigger_error().

Configuração recomendada por ambiente

Em vez de dispersar as configurações, coloque-as no topo do arquivo de bootstrap.

<?php
// --- Development ---
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');

<?php
// --- Production ---
error_reporting(E_ALL);          // still GENERATE everything...
ini_set('display_errors', '0');  // ...but never show it to users...
ini_set('log_errors', '1');      // ...log it instead.
ini_set('error_log', '/var/log/php_errors.log');

O bloco de produção mantém visibilidade total através dos logs sem expor nada aos visitantes — a configuração que você quase sempre deseja em um servidor em produção.

Boas práticas

• Nunca execute a produção com display_errors ativo. Caminhos e rastreamentos de pilha expostos são um risco de divulgação de informações.
• Reporte em E_ALL em todos os lugares. Reportar e exibir são coisas separadas; suprimir níveis apenas esconde bugs.
• Evite o operador de supressão de erros @. Ele esconde erros no local da chamada e torna a depuração muito mais difícil; trate a condição explicitamente.
• Capture o que puder como exceções. Para falhas recuperáveis, prefira try/catch em vez de handlers de erro. Veja PHP Exceptions.
• Use uma biblioteca de logging em aplicações maiores. Ferramentas como Monolog oferecem níveis de log, rotação e múltiplos destinos além do error_log().

Conclusão

O relatório de erros em PHP resume-se a três camadas: escolher os níveis com error_reporting(), escolher o destino com display_errors / log_errors, e opcionalmente personalizar o tratamento com set_error_handler() e trigger_error(). Configure-os deliberadamente — verboso na tela durante o desenvolvimento, silencioso mas registrado em produção — e você terá depuração rápida sem expor sua aplicação a usuários ou atacantes.

Leitura relacionada: PHP Error handling · error_get_last() · try…catch.

Prática