trigger_error()

Introducción

trigger_error() permite que tu propio código genere un mensaje de error de PHP de la misma forma en que el motor genera los errores integrados. Es la forma estándar de señalar que una función fue llamada incorrectamente — un argumento faltante, un valor fuera de rango, una llamada obsoleta — sin lanzar una excepción ni imprimir un echo ad-hoc. Dado que el mensaje fluye a través del canal de errores normal de PHP, respeta error_reporting, puede registrarse automáticamente y puede ser interceptado por un manejador de errores personalizado.

Esta página explica qué hace trigger_error(), su sintaxis y niveles de error, y muestra un ejemplo ejecutable para cada nivel, además de un caso de uso práctico de validación de entrada.

¿Qué es la función trigger_error()?

trigger_error() genera un error de nivel de usuario — un error que tu programa genera a propósito, a diferencia de uno que el motor de PHP genera por sí solo. Cuando la llamas, PHP se comporta exactamente como si hubiera encontrado ese error por sí mismo: aplica la máscara actual de error_reporting, envía el mensaje al manejador de errores activo (o al predeterminado) y puede detener el script según el nivel.

Hay dos cosas que es fácil confundir:

• trigger_error() genera un error, no una excepción. No será capturado por try/catch a menos que un manejador personalizado lo convierta en una excepción (un patrón común que se muestra a continuación).
• La función siempre devuelve false, por lo que return trigger_error(...) rara vez es lo que deseas.

Sintaxis de trigger_error()

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

El nivel de error debe ser uno de:

• E_USER_ERROR — un error fatal. Con el manejador predeterminado detiene el script de inmediato. Con un manejador personalizado el script continúa a menos que el manejador lo detenga (devuelve false y deja que PHP continúe, o llama a exit()).
• E_USER_WARNING — una advertencia no fatal. El script sigue ejecutándose.
• E_USER_NOTICE — un mensaje informativo. El script sigue ejecutándose. Este es el valor predeterminado.

Pasar cualquier otra constante (por ejemplo E_WARNING) genera su propio E_USER_WARNING e ignora tu valor.

trigger_error() respeta el nivel actual de error_reporting: si el nivel activado está enmascarado, no se reporta nada. Entonces, si se establece error_reporting(E_ALL & ~E_USER_NOTICE), un aviso que generes se descarta silenciosamente.

Aviso para PHP 8.4+: activar E_USER_ERROR está obsoleto. Lanzar una excepción es ahora la forma recomendada de señalar una condición fatal a nivel de usuario. Los otros dos niveles siguen siendo totalmente compatibles.

Un aviso simple con el manejador predeterminado

El uso mínimo de trigger_error() es una sola llamada. Con el manejador de errores predeterminado de PHP y la visualización habilitada, imprime una línea formateada y la ejecución continúa (los avisos no son fatales):

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

Salida (con display_errors activado):

Before

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

El script llega al echo final porque un aviso no detiene la ejecución.

Distinguir los niveles con un manejador personalizado

Un manejador de errores personalizado te da control total sobre cómo se representa cada nivel. El manejador recibe el número de nivel como $errno, por lo que puedes mapearlo a una etiqueta y decidir qué hacer a continuación.

<?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";

Salida:

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

El manejador devuelve true, indicándole a PHP que el error fue manejado, por lo que se omite el manejador predeterminado y el script continúa. El caso E_USER_ERROR se mantiene en el match por completitud, pero ten en cuenta que con el manejador predeterminado un E_USER_ERROR detendría el script antes de "Script finished" — y en PHP 8.4+ activar ese nivel está obsoleto.

Uso práctico: validar argumentos de función

El uso real más común de trigger_error() es proteger una función contra entradas incorrectas — emitir una advertencia cuando quien la llama pasa algo inválido y luego devolver un valor seguro por defecto:

<?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

Salida (con display_errors activado):

5

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

Este patrón mantiene el seguimiento de pila y el número de línea del llamador en el mensaje, lo que facilita enormemente encontrar la llamada incorrecta en comparación con un echo sin más.

Convertir errores en excepciones

Si prefieres manejar problemas con try/catch, un manejador personalizado puede convertir un error activado en una ErrorException. Este es el puente entre el sistema de errores de PHP y su sistema de excepciones:

<?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";
}

Salida:

Caught: Recoverable problem

Dado que el manejador lanza una excepción, la advertencia nunca llega a la salida de errores predeterminada — se entrega a tu bloque catch en su lugar.

Errores comunes

• No es una excepción. Sin un manejador que lance excepciones, try/catch no capturará un error activado.
• error_reporting puede ocultarlo. Si el nivel está enmascarado, tu mensaje desaparece sin ninguna indicación. Comprueba el nivel actual con error_reporting().
• E_USER_ERROR está obsoleto en PHP 8.4+. Lanza una excepción (o llama a die()) para condiciones fatales a nivel de usuario en su lugar.
• El mensaje se trunca a 1024 bytes — mantenlo conciso.

Conclusión

trigger_error() es la forma idiomática de generar un E_USER_NOTICE, E_USER_WARNING o (heredado) E_USER_ERROR a nivel de usuario. Conecta tus mensajes al canal estándar de PHP para que respeten error_reporting, puedan registrarse e interceptarse mediante un manejador de errores personalizado — o convertirse en excepciones cuando deseas la semántica de try/catch. Para nuevo código a nivel fatal, prefiere lanzar excepciones en lugar de E_USER_ERROR.

Práctica