trigger_error()

Introdução

trigger_error() permite que seu próprio código gere uma mensagem de erro PHP da mesma forma que o motor gera as embutidas. É a maneira padrão de sinalizar que uma função foi chamada incorretamente — um argumento ausente, um valor fora do intervalo, uma chamada obsoleta — sem lançar uma exceção ou imprimir um echo improvisado. Como a mensagem flui pelo pipeline de erros normal do PHP, ela respeita error_reporting, pode ser registrada automaticamente e pode ser interceptada por um handler de erro personalizado.

Esta página explica o que trigger_error() faz, sua sintaxe e níveis de erro, e mostra um exemplo executável para cada nível, além de um caso de uso prático de validação de entrada.

O que é a função trigger_error()?

trigger_error() gera um erro de nível de usuário — um erro que seu programa gera propositalmente, em oposição a um que o motor PHP gera por conta própria. Quando você a chama, o PHP se comporta exatamente como se tivesse encontrado esse erro por si mesmo: aplica a máscara error_reporting atual, envia a mensagem para o handler de erro ativo (ou o padrão) e pode interromper o script dependendo do nível.

Dois pontos são fáceis de entender errado:

• trigger_error() gera um erro, não uma exceção. Não será capturado por try/catch, a menos que um handler personalizado o converta em uma exceção (um padrão comum mostrado abaixo).
• A função sempre retorna false, portanto return trigger_error(...) raramente é o que você deseja.

Sintaxe de trigger_error()

trigger_error(string $message, int $error_level = E_USER_NOTICE): bool

O nível de erro deve ser um dos seguintes:

• E_USER_ERROR — um erro fatal. Com o handler padrão, interrompe o script imediatamente. Com um handler personalizado, o script continua a menos que o handler o interrompa (retorne false e deixe o PHP prosseguir, ou chame exit()).
• E_USER_WARNING — um aviso não fatal. O script continua em execução.
• E_USER_NOTICE — uma mensagem informativa. O script continua em execução. Este é o padrão.

Passar qualquer outra constante (por exemplo E_WARNING) gera um E_USER_WARNING próprio e ignora seu valor.

trigger_error() respeita o nível atual de error_reporting: se o nível disparado estiver mascarado, nada é reportado. Portanto, se error_reporting(E_ALL & ~E_USER_NOTICE) estiver definido, um aviso que você dispara é descartado silenciosamente.

Atenção para PHP 8.4+: disparar E_USER_ERROR está obsoleto. Lançar uma exceção é agora a forma recomendada de sinalizar uma condição fatal de nível de usuário. Os outros dois níveis permanecem totalmente suportados.

Um aviso simples com o handler padrão

O uso mínimo de trigger_error() é uma única chamada. Com o handler de erro padrão do PHP e exibição habilitada, ele imprime uma linha formatada e a execução continua (avisos não são fatais):

<?php
echo "Before\n";
trigger_error("Something worth noting", E_USER_NOTICE);
echo "After\n";

Saída (com display_errors ativado):

Before

Notice: Something worth noting in /path/to/script.php on line 3
After

O script chega ao echo final porque um aviso não interrompe a execução.

Distinguindo os níveis com um handler personalizado

Um handler de erro personalizado oferece controle total sobre como cada nível é renderizado. O handler recebe o número do nível como $errno, permitindo mapeá-lo para um rótulo e decidir o que fazer a seguir.

<?php
function custom_error_handler($errno, $errstr, $errfile, $errline) {
  $label = match ($errno) {
    E_USER_ERROR   => 'ERROR',
    E_USER_WARNING => 'WARNING',
    E_USER_NOTICE  => 'NOTICE',
    default        => 'UNKNOWN',
  };
  echo "[$label] $errstr (line $errline)\n";
  // Returning true tells PHP we handled it, so the default handler is skipped.
  return true;
}

set_error_handler("custom_error_handler");

trigger_error("Disk is almost full", E_USER_NOTICE);
trigger_error("Cache miss, falling back to DB", E_USER_WARNING);

echo "Script finished\n";

Saída:

[NOTICE] Disk is almost full (line 16)
[WARNING] Cache miss, falling back to DB (line 17)
Script finished

O handler retorna true, informando ao PHP que o erro foi tratado, portanto o handler padrão é ignorado e o script continua. O ramo E_USER_ERROR é mantido no match por completude, mas observe que com o handler padrão um E_USER_ERROR interromperia o script antes de "Script finished" — e no PHP 8.4+ disparar esse nível está obsoleto.

Uso prático: validando argumentos de função

O uso mais comum no mundo real de trigger_error() é proteger uma função contra entradas incorretas — emitindo um aviso quando um chamador passa algo inválido, depois retornando um valor padrão seguro:

<?php
function divide($a, $b) {
  if ($b == 0) {
    trigger_error("divide(): division by zero, returning 0", E_USER_WARNING);
    return 0;
  }
  return $a / $b;
}

echo divide(10, 2), "\n";   // 5
echo divide(10, 0), "\n";   // warning + 0

Saída (com display_errors ativado):

5

Warning: divide(): division by zero, returning 0 in /path/to/script.php on line 4
0

Esse padrão mantém o rastreamento de pilha e o número de linha do chamador na mensagem, tornando muito mais fácil encontrar a chamada ofensora do que um echo simples.

Convertendo erros em exceções

Se preferir tratar problemas com try/catch, um handler personalizado pode transformar um erro disparado em um ErrorException. Esta é a ponte entre o sistema de erros do PHP e seu sistema de exceções:

<?php
set_error_handler(function ($errno, $errstr, $errfile, $errline) {
  throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
});

try {
  trigger_error("Recoverable problem", E_USER_WARNING);
} catch (ErrorException $e) {
  echo "Caught: " . $e->getMessage() . "\n";
}

Saída:

Caught: Recoverable problem

Como o handler lança uma exceção, o aviso nunca chega à saída de erro padrão — ele é entregue ao seu bloco catch.

Armadilhas comuns

• Não é uma exceção. Sem um handler que lance, try/catch não capturará um erro disparado.
• error_reporting pode ocultá-lo. Se o nível estiver mascarado, sua mensagem desaparece sem indicação. Verifique o nível atual com error_reporting().
• E_USER_ERROR está obsoleto no PHP 8.4+. Lance uma exceção (ou chame die()) para condições fatais de nível de usuário.
• A mensagem é truncada em 1024 bytes — mantenha-a concisa.

Conclusão

trigger_error() é a forma idiomática de gerar um E_USER_NOTICE, E_USER_WARNING ou (legado) E_USER_ERROR de nível de usuário. Ele conecta suas mensagens ao pipeline padrão do PHP para que respeitem error_reporting, possam ser registradas e possam ser interceptadas por um handler de erro personalizado — ou convertidas em exceções quando você deseja semântica try/catch. Para novo código de nível fatal, prefira lançar exceções em vez de usar E_USER_ERROR.

Prática