Manuel PHP
Précédent |  | Suivant

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5)

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

## Description

string set_error_handler ( callback error_handler [, int error_types])

set_error_handler() choisit la fonction utilisateur `error_handler` pour gérer les erreurs dans un script. Retourne un pointeur sur l'ancienne fonction de gestion des erreurs (s'l y en avait une), ou `FALSE`, en cas d'erreur. set_error_handler() sert à définir votre propre gestionnaire d'erreurs, qui prendra en charge leur traitement durant l'exécution d'un script. Cela peut être utile lorsque vous devez repérer des erreurs critiques lors d'un nettoyage de bases, ou bien si vous souhaitez générer une erreur dans certaines conditions (avec trigger_error()).

Le second paramètre `error_types` a été introduit en `PHP` 5, et sert de masque pour appeler la fonction `error_handler` de la même façon que l'option de configuration error_reporting contrôle les erreurs qui sont affichées. Sans le masque, `error_handler` sera appelé pour toutes les erreurs, quelque soit la valeur de error_reporting.

La fonction utilisateur doit accepter deux paramètres : le code d'erreur et une chaîne décrivant le code d'erreur. Depuis `PHP` 4.0.2, trois paramètres optionnels sont fournis en même temps : le fichier dans lequel l'erreur est survenue, la ligne à laquelle l'erreur est survenue, et le contexte dans lequel l'erreu est survenue (un tableau contenant la liste des symboles lors de l'erreur). La fonction peut être décrite comme ceci : `handler` ( int errno, string errstr [, string errfile [, int errline [, array errcontext]]])

`errno`

  Le premier paramètre `errno`, contient le niveau d'erreur, sous la forme d'un entier.

`errstr`

  Le second paramètre `errstr`, contient le message d'erreur, sous forme de chaîne.

`errfile`

  Le troisième paramètre, optionnel, `errfile`, contient le nom du fichier dans lequel l'erreur a été identifiée.

`errline`

  Le quatrième paramètre, optionnel, `errline`, contient le numéro de ligne à laquelle l'erreur a été identifiée.

`errcontext`

  Le cinquième paramètre, optionnel, `errcontext`, est un tableaui qui pointe sur la table des symboles actifs lors de l'erreur. En d'autres termes, `errcontext` contient un tableau avec toutes les variables qui existaient lorsque l'erreur a été déclenchée.

> Note : Au lieu d'un nom de fonction, vous pouvez utiliser un tableau contenant deux éléments, une référence sur un objet et un nom de méthode. Cette fonctionnalité a été ajoutée en PHP 4.3.0.

> Note : 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` et `E_STRICT`.

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

Exemple 1. Traitement des erreurs avec set_error_handler() et trigger_error()

`<?php
// redéfini les constantes utilisateur (PHP 4 Uniquement)
define ("FATAL",E_USER_ERROR);
define ("ERROR",E_USER_WARNING);
define ("WARNING",E_USER_NOTICE);
// configure le niveau de rapport d'erreur pour ce script
error_reporting (FATAL | ERROR | WARNING);
// gestionnaire d'erreurs
function myErrorHandler ($errno, $errstr, $errfile, $errline)
{
switch ($errno) {
case FATAL:
echo "<b>FATAL</b> [$errno] $errstr<br />\n";
echo " Fatal error in line ".$errline." of file ".$errfile;
echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br />\n";
echo "Aborting...<br>\n";
exit(1);
break;
case ERROR:
echo "<b>ERROR</b> [$errno] $errstr<br />\n";
break;
case WARNING:
echo "<b>WARNING</b> [$errno] $errstr<br />\n";
break;
default:
echo "Unkown error type: [$errno] $errstr<br />\n";
break;
}
}
// fonction pour tester la gestion d'erreur
function scale_by_log ($vect, $scale)
{
if ( !is_numeric($scale) || $scale <= 0 ) {
trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale",
FATAL);
}
if (!is_array($vect)) {
trigger_error("Incorrect input vector, array of values expected", ERROR);
return null;
}
for ($i=0; $i<count($vect); $i++) {
if (!is_numeric($vect[$i]))
trigger_error("Value at position $i is not a number, using 0 (zero)",
WARNING);
$temp[$i] = log($scale) * $vect[$i];
}
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 "vecteur a \n";
$a = array(2,3,"foo",5.5,43.3,21.11);
print_r($a);
// générons maintenant un autre tableau, avec des alertes
echo "----\nvecteur b - une alerte (b = log(PI) * a)\n";
$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 "----\nvecteur c - une erreur\n";
$c = scale_by_log("not array",2.3);
var_dump($c);
// Ceci est une erreur critique : le logarithme de zéro ou d'un nombre négatif est indéfini
echo "----\nvecteur d - erreur fatale\n";
$d = scale_by_log($a, -2.5);
?>`

L'exécution du script devrait donner ceci :

Exemple 2. Résultat de set_error_handler() et trigger_error()

    vecteur a
    Array
    (
        [0] => 2
        [1] => 3
        [2] => foo
        [3] => 5.5
        [4] => 43.3
        [5] => 21.11
    )
    ----
    vecteur b - une alerte (b = log(PI) * a)
    <b>WARNING</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />
    Array
    (
        [0] => 2.2894597716988
        [1] => 3.4341896575482
        [2] => 0
        [3] => 6.2960143721717
        [4] => 49.566804057279
        [5] => 24.165247890281
    )
    ----
    vecteur c - une erreur
    <b>ERROR</b> [512] Incorrect input vector, array of values expected<br />
    NULL
    ----
    vecteur d - erreur fatale
    <b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />
      Fatal error in line 37 of file /Users/imac/-, PHP 5.0.0-dev (Darwin)<br />
    Aborting...<br />

Il faut se rappeler que la fonction standard de traitement des erreurs de PHP est alors complètement ignorée. error_reporting() n'aura plus d'effet, et votre fonction de gestion des erreurs sera toujours appelée. Vous pourrez toujours lire la valeur de l'erreur courante de error_reporting() et faire réagir la fonction de gestion des erreurs en fonction. Cette remarque est notamment valable si la commande a été préfixée par @ (0 sera retourné).

Notez aussi qu'il est alors confié à cette fonction de terminer le script (die()) si nécessaire. Si la fonction de gestion des erreurs se termine normalement, l'exécution du script se poursuivra avec l'exécution de la prochaine commande.

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

> Note : La second paramètre `error_types` a été introduit en `PHP` 5.

Voir aussi error_reporting(), restore_error_handler(), trigger_error() et les constantes de niveau d'erreurs.

Précédent | Sommaire | Suivant
restore_error_handler | Niveau supérieur | trigger_error