trigger_error()

Introduction

trigger_error() permet à votre propre code de lever un message d'erreur PHP de la même manière que le moteur lève ses erreurs intégrées. C'est la façon standard de signaler qu'une fonction a été appelée incorrectement — un argument manquant, une valeur hors limites, un appel obsolète — sans lancer une exception ni afficher un echo improvisé. Comme le message transite par le pipeline d'erreur normal de PHP, il respecte error_reporting, peut être journalisé automatiquement, et peut être intercepté par un gestionnaire d'erreurs personnalisé.

Cette page explique ce que fait trigger_error(), sa syntaxe et ses niveaux d'erreur, et présente un exemple exécutable pour chaque niveau ainsi qu'un cas d'usage pratique de validation de saisie.

Qu'est-ce que la fonction trigger_error() ?

trigger_error() lève une erreur de niveau utilisateur — une erreur que votre programme génère intentionnellement, par opposition à une erreur levée par le moteur PHP lui-même. Quand vous l'appelez, PHP se comporte exactement comme s'il avait rencontré cette erreur de lui-même : il applique le masque error_reporting courant, envoie le message au gestionnaire d'erreurs actif (ou au gestionnaire par défaut), et peut interrompre le script selon le niveau.

Deux points sont faciles à mal interpréter :

• trigger_error() lève une erreur, pas une exception. Elle ne sera pas attrapée par try/catch à moins qu'un gestionnaire personnalisé ne la convertisse en exception (un schéma courant présenté ci-dessous).
• La fonction retourne toujours false, donc return trigger_error(...) est rarement ce que vous souhaitez.

Syntaxe de trigger_error()

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

Le niveau d'erreur doit être l'un des suivants :

• E_USER_ERROR — une erreur fatale. Avec le gestionnaire par défaut, le script s'arrête immédiatement. Avec un gestionnaire personnalisé, le script continue à moins que le gestionnaire ne l'arrête (retourne false et laisse PHP prendre le relais, ou appelle exit()).
• E_USER_WARNING — un avertissement non fatal. Le script continue à s'exécuter.
• E_USER_NOTICE — un message informatif. Le script continue à s'exécuter. C'est la valeur par défaut.

Passer toute autre constante (par exemple E_WARNING) lève un E_USER_WARNING de son propre chef et ignore votre valeur.

trigger_error() respecte le niveau error_reporting courant : si le niveau déclenché est masqué, rien n'est signalé. Donc si error_reporting(E_ALL & ~E_USER_NOTICE) est défini, une notice que vous déclenchez est silencieusement ignorée.

Note pour PHP 8.4+ : déclencher E_USER_ERROR est déprécié. Lancer une exception est désormais la façon recommandée de signaler une condition fatale de niveau utilisateur. Les deux autres niveaux restent entièrement supportés.

Une notice simple avec le gestionnaire par défaut

L'utilisation minimale de trigger_error() est un seul appel. Avec le gestionnaire d'erreurs par défaut de PHP et l'affichage activé, il affiche une ligne formatée et l'exécution continue (les notices ne sont pas fatales) :

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

Sortie (avec display_errors activé) :

Before

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

Le script atteint le dernier echo car une notice n'arrête pas l'exécution.

Distinguer les niveaux avec un gestionnaire personnalisé

Un gestionnaire d'erreurs personnalisé vous donne un contrôle total sur le rendu de chaque niveau. Le gestionnaire reçoit le numéro de niveau en tant que $errno, vous pouvez donc le mapper vers un libellé et décider de la suite.

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

Sortie :

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

Le gestionnaire retourne true, indiquant à PHP que l'erreur a été gérée, donc le gestionnaire par défaut est ignoré et le script continue. Le cas E_USER_ERROR est conservé dans le match pour la complétude, mais notez qu'avec le gestionnaire par défaut, un E_USER_ERROR arrêterait le script avant "Script finished" — et sur PHP 8.4+, déclencher ce niveau est déprécié.

Cas pratique : validation des arguments de fonction

L'utilisation la plus courante de trigger_error() dans le monde réel est de protéger une fonction contre une saisie incorrecte — en émettant un avertissement quand un appelant passe quelque chose d'invalide, puis en retournant une valeur par défaut sûre :

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

Sortie (avec display_errors activé) :

5

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

Ce schéma conserve la trace de pile et le numéro de ligne de l'appelant dans le message, ce qui rend bien plus facile la localisation de l'appel problématique qu'un simple echo.

Convertir les erreurs en exceptions

Si vous préférez gérer les problèmes avec try/catch, un gestionnaire personnalisé peut transformer une erreur déclenchée en ErrorException. C'est le pont entre le système d'erreurs de PHP et son système d'exceptions :

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

Sortie :

Caught: Recoverable problem

Comme le gestionnaire lance une exception, l'avertissement n'atteint jamais la sortie d'erreur par défaut — il est livré à votre bloc catch à la place.

Pièges courants

• Ce n'est pas une exception. Sans un gestionnaire qui lance une exception, try/catch n'attrapera pas une erreur déclenchée.
• error_reporting peut la masquer. Si le niveau est désactivé, votre message disparaît sans indication. Vérifiez le niveau courant avec error_reporting().
• E_USER_ERROR est déprécié dans PHP 8.4+. Lancez une exception (ou appelez die()) pour les conditions fatales de niveau utilisateur à la place.
• Le message est tronqué à 1024 octets — gardez-le concis.

Conclusion

trigger_error() est la façon idiomatique de lever un E_USER_NOTICE, E_USER_WARNING ou (hérité) E_USER_ERROR de niveau utilisateur. Elle intègre vos messages dans le pipeline standard de PHP afin qu'ils respectent error_reporting, puissent être journalisés, et puissent être interceptés par un gestionnaire d'erreurs personnalisé — ou convertis en exceptions quand vous souhaitez la sémantique try/catch. Pour le nouveau code de niveau fatal, préférez lancer des exceptions plutôt qu'utiliser E_USER_ERROR.

Pratique