set_error_handler
PHP Manual
PHP Manual»Fonctions sur la gestion des erreurs»set_error_handler

set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — Spécifie une fonction utilisateur comme gestionnaire d'erreurs

Description

function set_error_handler(?callable $callback, int $error_levels = E_ALL): ?callable

set_error_handler() choisit la fonction utilisateur callback pour gérer les erreurs dans un script. Le gestionnaire actif jusqu'alors est sauvegardé sur une pile interne de gestionnaires d'erreurs, d'où restore_error_handler() le dépile.

Cette fonction peut être utilisée pour définir des gestionnaires d'erreurs personnalisés pendant l'exécution, par exemple dans des applications qui ont besoin de nettoyer des fichiers/données lorsqu'une erreur critique se produit ou lorsqu'une erreur est déclenchée en réponse à certaines conditions (à l'aide de la fonction trigger_error()).

Il faut se rappeler que la fonction standard de traitement des erreurs de PHP est alors complètement ignorée pour les erreurs de types spécifiés par error_levels à moins que la fonction de rappel retourne false. Les paramètres de la fonction error_reporting() n'auront aucun effet et le gestionnaire d'erreurs sera appelé quoi qu'il arrive. Cependant, il est toujours possible de lire la valeur actuelle de error_reporting et de faire réagir la fonction de gestion des erreurs en conséquence.

Il est à noter que c'est la responsabilité du gestionnaire d'erreurs d'arrêter l'exécution du script si nécessaire en appelant la fonction exit(). Si la fonction du gestionnaire d'erreurs retourne, l'exécution du script se poursuivra avec l'instruction suivante après celle qui a causé l'erreur.

Les types d'erreur suivants ne peuvent pas être gérés avec cette fonction : E_ERROR, E_PARSE, E_CORE_ERROR, E_CORE_WARNING, E_COMPILE_ERROR, E_COMPILE_WARNING indépendamment d'où elles sont levées, ainsi que la plupart des E_STRICT du fichier dans lequel set_error_handler() est appelé.

Si une erreur survient avant que le script ne soit exécuté (par exemple un téléversement de fichier), le gestionnaire d'erreurs personnalisé ne pourra pas être appelé, car il n'est pas encore enregistré.

Liste de paramètres

callback

Si null est fourni, aucun gestionnaire utilisateur ne reste actif et les erreurs sont traitées par le gestionnaire d'erreurs interne. Le gestionnaire actif jusqu'alors est toujours sauvegardé sur la pile et peut être rétabli avec restore_error_handler(). Sinon, le gestionnaire est une fonction de rappel avec la signature suivante :

function handler(
    int $errno,
    string $errstr,
    string $errfile = ?,
    int $errline = ?,
    array $errcontext = ?
): bool
errno

Le premier paramètre errno, sera passé le niveau d'erreur, sous la forme d'un entier.

errstr

Le second paramètre errstr, sera passé le message d'erreur, sous forme de chaîne.

errfile

Si la fonction de rappel accepte un troisième paramètre, errfile, il sera passé le nom du fichier dans lequel l'erreur a été identifiée, sous forme de chaîne.

errline

Si la fonction de rappel accepte un quatrième paramètre, errline, il sera passé le numéro de ligne à laquelle l'erreur a été identifiée, sous la forme d'un entier.

errcontext

Si la fonction de rappel accepte un cinquième paramètre, errcontext, il sera passé comme un tableau qui pointe sur la table des symboles actifs à l'instant où l'erreur est survenue. En d'autres termes, errcontext contient un tableau avec toutes les variables qui existaient lorsque l'erreur a été déclenchée. Les gestionnaires d'erreurs utilisateur ne doivent pas modifier le contexte d'erreur.

Avertissement

Ce paramètre est OBSOLÈTE à partir de PHP 7.2.0, et SUPPRIMÉ à partir de PHP 8.0.0. Si la fonction définit ce paramètre sans valeur par défaut, une erreur de "too few arguments" sera levée lors de son appel.

Si la fonction retourne false, alors le gestionnaire d'erreurs normal continue.

error_levels

Sert de masque pour appeler la fonction callback de la même façon que l'option de configuration error_reporting contrôle les erreurs qui sont affichées. Sans le masque, callback sera appelé pour toutes les erreurs, quelle que soit la valeur de error_reporting.

Valeurs de retour

Retourne le dernier gestionnaire d'erreurs (s'il existe) sous forme de callable. Si le gestionnaire d’erreurs interne est utilisé, null est retourné.

Historique

Version Description
8.0.0 errcontext a été supprimé, et ne sera plus passé aux fermetures utilisateur.
7.2.0 errcontext est devenu obsolète. L'usage de ce paramètre émet une notice E_DEPRECATED.

Exemples

Exemple #1 Gestionnaire d'erreurs avec set_error_handler() et trigger_error()

L'exemple ci-dessous illustre l'interception d'erreurs internes avec génération d'erreur et son exploitation dans une fonction utilisateur :

<?php
// Gestionnaire d'erreurs
function myErrorHandler($errno, $errstr, $errfile, $errline)
{
   if (!(error_reporting() & $errno)) {
        // Ce code d'erreur n'est pas inclus dans error_reporting(), donc il continue
        // jusqu'au gestionnaire d'erreur standard de PHP
        return false;
    }

    // $errstr doit peut-être être échappé :
    $errstr = htmlspecialchars($errstr);

    switch ($errno) {
    case E_USER_ERROR:
        echo "<b>Mon ERREUR</b> [$errno] $errstr<br />\n";
        echo "  Erreur fatale sur la ligne $errline dans le fichier $errfile";
        echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";
        echo "Arrêt...<br />\n";
        exit(1);

    case E_USER_WARNING:
        echo "<b>Mon ALERTE</b> [$errno] $errstr<br />\n";
        break;

    case E_USER_NOTICE:
        echo "<b>Mon AVERTISSEMENT</b> [$errno] $errstr<br />\n";
        break;

    default:
        echo "Type d'erreur inconnu : [$errno] $errstr<br />\n";
        break;
    }

    /* Ne pas exécuter le gestionnaire interne de PHP */
    return true;
}

// Fonction pour tester la gestion d'erreur
function scale_by_log($vect, $scale)
{
    if (!is_numeric($scale) || $scale <= 0) {
        trigger_error("log(x) pour x <= 0 est indéfini, valeur utilisée : scale = $scale", E_USER_ERROR);
    }

    if (!is_array($vect)) {
        trigger_error("Type d'entrée incorrect, tableau de valeurs attendu", E_USER_WARNING);
        return null;
    }

    $temp = array();
    foreach($vect as $pos => $value) {
        if (!is_numeric($value)) {
            trigger_error("La valeur à la position $pos n'est pas un nombre, utilisation 0 (zéro)", E_USER_NOTICE);
            $value = 0;
        }
        $temp[$pos] = log($scale) * $value;
    }
    return $temp;
  }

// Configuration du gestionnaire d'erreurs
$old_error_handler = set_error_handler("myErrorHandler");

// Génération de quelques erreurs. Commençons par créer un tableau
echo "vector a\n";
$a = array(2, 3, "foo", 5.5, 43.3, 21.11);
print_r($a);

// Générons maintenant un second tableau
echo "----\nvector b - a notice (b = log(PI) * a)\n";
/* La valeur à la position $pos n'est pas un nombre, utilisation 0 (zéro) */
$b = scale_by_log($a, M_PI);
print_r($b);

// Ceci est un problème, nous avons utilisé une chaîne au lieu d'un tableau
echo "----\nvector c - a warning\n";
/* Type d'entrée incorrect, tableau de valeurs attendu */
$c = scale_by_log("non un tableau", 2.3);
var_dump($c); // NULL

// Ceci est une erreur critique : le logarithme de zéro ou d'un nombre négatif est indéfini
echo "----\nvector d - fatal error\n";
/* log(x) pour x <= 0 est indéfini, valeur utilisée : scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Jamais atteint
?>

Résultat de l'exemple ci-dessus est similaire à :

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a notice (b = log(PI) * a)
<b>Mon AVERTISSEMENT</b> [1024] La valeur à la position 2 n'est pas un nombre, utilisation 0 (zéro)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - a warning
<b>Mon ALERTE</b> [512] Type d'entrée incorrect, tableau de valeurs attendu<br />
NULL
----
vector d - fatal error
<b>Mon ERREUR</b> [256] log(x) pour x <= 0 est indéfini, valeur utilisée : scale = -2.5<br />
  Erreur fatale sur la ligne 36 dans le fichier trigger_error.php, PHP 5.2.1 (Linux)<br />
Arrêt...<br />

Exemple #2 Appel du gestionnaire précédent depuis le nouveau

La valeur de retour de set_error_handler() est le gestionnaire qui était actif jusqu'alors. L'appeler depuis le nouveau gestionnaire conserve le comportement existant tout en le complétant. Cela ne fonctionne que si ce gestionnaire est une fonction utilisateur ; null est retourné lorsque le gestionnaire interne était actif.

<?php
function logging_handler(int $errno, string $errstr): bool
{
    echo "journalisé : $errstr\n";
    return true;
}

set_error_handler('logging_handler');

$previous = set_error_handler(function (int $errno, string $errstr) use (&$previous): bool {
    echo "compté : $errstr\n";
    return $previous !== null ? $previous($errno, $errstr) : false;
});

trigger_error("quelque chose s'est produit", E_USER_WARNING);

restore_error_handler();
trigger_error("seulement journalisé maintenant", E_USER_WARNING);

restore_error_handler();
?>

L'exemple ci-dessus va afficher :

compté : quelque chose s'est produit
journalisé : quelque chose s'est produit
journalisé : seulement journalisé maintenant

Notes

Attention

Il ne faut pas revenir au gestionnaire précédent en repassant à set_error_handler() sa valeur de retour. Cela empile une entrée supplémentaire au lieu d'en retirer une, si bien que la pile croît sans limite dans les boucles et les processus de longue durée, et error_levels est réinitialisé à E_ALL, élargissant silencieusement la plage des erreurs que reçoit le gestionnaire restauré. restore_error_handler() est la façon prévue de revenir au gestionnaire précédent.

Voir aussi

To Top