Manuel PHP
Précédent |  | Suivant

# XXXII. Gestion des erreurs

# Introduction

Ces fonctions permettent de gérer les erreurs et de les enregistrer. Vous pouvez définir les règles de traitement des erreurs et choisir la manière de les enregistrer : vous pouvez adapter le rapport d'erreurs à vos besoins.

Avec les fonctions d'enregistrements, vous pouvez envoyer directement les rapports à d'autres machines (ou même les envoyer par email à un pager), à l'historique système, ou encore sélectionner les erreurs les plus importantes et ne pas enregistrer les autres.

La fonction de niveau d'erreur vous permet de personnaliser le niveau et le type d'erreur noté : depuis les inoffensives alertes jusqu'aux erreurs personnalisées retournées par les fonctions.

# Pré-requis

Ces fonctions sont disponibles dans le module PHP standard, qui est toujours accessible.

# Installation

Il n'y pas d'installation nécessaire pour utiliser ces fonctions, elles font parties du coeur de PHP.

# Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier `php.ini`.

Tableau 1. Options de configuration

Nom | Par défaut | Modifiable | Historique
--- | --- | --- | ---
error_reporting | NULL | PHP_INI_ALL |
display_errors | "1" | PHP_INI_ALL |
display_startup_errors | "0" | PHP_INI_ALL | Disponible depuis PHP 4.0.3.
log_errors | "0" | PHP_INI_ALL |
log_errors_max_len | "1024" | PHP_INI_ALL | Disponible depuis PHP 4.3.0.
ignore_repeated_errors | "0" | PHP_INI_ALL | Disponible depuis PHP 4.3.0.
ignore_repeated_source | "0" | PHP_INI_ALL | Disponible depuis PHP 4.3.0.
report_memleaks | "1" | PHP_INI_ALL | Disponible depuis PHP 4.3.0.
track_errors | "0" | PHP_INI_ALL |
html_errors | "1" | PHP_INI_ALL | PHP_INI_SYSTEM en PHP <=4.2.3. Disponible depuis PHP 4.0.2.
docref_root | "" | PHP_INI_ALL | Disponible depuis PHP 4.3.0.
docref_ext | "" | PHP_INI_ALL | Disponible depuis PHP 4.3.2.
error_prepend_string | NULL | PHP_INI_ALL |
error_append_string | NULL | PHP_INI_ALL |
error_log | NULL | PHP_INI_ALL |
warn_plus_overloading | NULL | PHP_INI?? |

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à Annexe G.

Voici un éclaircissement sur l'utilisation des directives de configuration.

error_reporting entier

  Fixe le niveau d'erreur. Ce paramètre est un entier, représentant un champ de bits. Ajoutez les valeurs suivantes pour choisir le niveau que vous désirez, telles que décrites dans la section Constantes pré-définies, et dans le fichier `php.ini`. Pour modifier cette configuration durant l'exécution du script, utilisez la fonction error_reporting(). Voyez aussi la directive display_errors.

  En PHP 4 et PHP 5, la configuration par défaut est `E_ALL` & ~`E_NOTICE`. Elle montre toutes les erreurs, sauf les `E_NOTICE`. Il est recommandé de les afficher durant le développement.

  > Note : Activer le rapport d'erreur de niveau `E_NOTICE` durant le développement a des avantages. En terme de débogage, les message d'alertes vous signalent des bogues potentiels dans votre code. Par exemple, l'utilisation de valeurs non initialisées est signalée. Il est aussi plus pratique pour trouver des coquilles, et, ainsi, gagner du temps. Les messages NOTICE vous signaleront aussi les mauvaises pratiques de codage. Par exemple $arr[item] doit toujours être écrit $arr['item'] car PHP va considérer "item" comme une constante, au premier abord. Si cette constante n'est pas définie, alors il va l'utiliser comme une chaîne.

  > Note : En PHP 5, un nouveau niveau d'erreur nommé `E_STRICT` est disponible. Comme `E_STRICT` n'est pas inclus sans `E_ALL`, vous devez explicitement activer ce niveau d'erreur. Activer `E_STRICT` pendant le développement peut être bénéfique. Les messages STRICT vous aideront à utiliser la dernière et meilleure suggestion de méthode de codage, par exemple, vous alertera de l'utilisation de fonctions non recommandées.

  En PHP 3, la configuration par défaut est (E_ERROR | E_WARNING | E_PARSE), ce qui correspond à la même configuration qu'en PHP 4. Notez toutefois que les constantes ne sont pas supportées dans le `php3.ini` de PHP 3, et que le niveau d'erreur doit être spécifié numériquement, c'est à dire 7.

display_errors boolean

  Cette directive détermine si les erreurs doivent être affichées à l'écran ou non.

  > Note : C'est une directive nécessaire en développement mais qui ne doit jamais être utilisée sur un système en production. (e.g. systèmes connectés à Internet).

  > Note : Bien que display_errors peut être défini en cours d'exécution (avec la fonction ini_set()), il n'aura aucun effet si le script a des erreurs fatales, car l'action désirée au moment de l'exécution ne sera pas exécutée.

display_startup_errors boolean

  Même si display_errors est activé, des erreurs peuvent survenir lors de la séquence de démarrage de PHP, et ces erreurs sont cachées. Avec cette option, vous pouvez les afficher, ce qui est recommandé pour le débogage. En dehors de ce cas, il est fortement recommandé de laisser display_startup_errors à off.

log_errors boolean

  Indique où les messages d'erreur générés doivent être écrits : dans l'historique du serveur ou dans error_log. Cette fonction est spécifique aux serveurs.

  > Note : Il est recommandé d'utiliser l'historique d'erreur, plutôt que d'afficher les erreurs sur les sites de production.

log_errors_max_len entier

  Configure la taille maximale des erreurs qui seront enregistrées dans l'historique, en kilo octets. Dans les informations de error_log, l'origine est ajoutée. La valeur par défaut est de 1024. 0 signifie qu'il n'y a pas de limite de taille. Cette longueur est appliqué pour enregistrer dans l'historique les erreurs, afficher les erreurs et également à $php_errormsg.

  Lorsqu'un entier est utilisé, sa valeur est mesuré en octets. Vous pouvez également utiliser la notation sténographique comme décrit dans cette entrée de la FAQ..

ignore_repeated_errors boolean

  Ne pas enregistrer des messages répétitifs. Les erreurs répétées doivent survenir au même moment, à la même ligne et depuis le même fichier de script, jusqu'à ce que ignore_repeated_source soit mis à `TRUE`.

ignore_repeated_source boolean

  Ignore la source du message lors des messages répétés. Lorsque vous avez configuré cette option à On, vous n'enregistrerez pas les erreurs répétées provenant de fichiers et lignes de code différents.

report_memleaks boolean

  Si ce paramètre est mis à Off, alors les fuites de mémoires ne seront pas affichées (sur la sortie standard, stdout ou dans les logs). Cette option n'a d'effet que si PHP a été compilé avec l'option de débogage, et si error_reporting inclut `E_WARNING` dans sa liste.

track_errors boolean

  Si cette option est activée, le dernier message d'erreur sera placé dans la variable globale $php_errormsg.

html_errors boolean

  Désactive les balises HTML dans les messages d'erreurs. Le nouveau format d'erreurs HTML fournit des messages cliquables, qui redirige l'utilisateur vers la documentation de l'erreur ou de la fonction. Ces références sont affectées par docref_root et docref_ext.

docref_root string

  Le nouveau format d'erreur contient une référence à une page décrivant l'erreur, ou la fonction ayant causé l'erreur. Pour le manuel, vous pouvez télécharger ce dernier dans votre langue, et configurer cette option pour qu'elle pointe sur lui. Si votre copie du manuel est accessible à '/manual/', vous pouvez simplement utiliser `docref_root=/manual/`. De plus, vous devez configurer docref_ext pour qu'elle corresponde aux extensions de votre manuel. `docref_ext=.html`. Il est possible d'utiliser des références externes. Par exemple, vous pouvez utiliser `docref_root=http://manual/en/` ou `docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon&url=http%3A%2F%2Fwww.php.net%2F"`

  La plupart du temps, vous utilisez l'option docref_root avec un slash a la fin ('/'). Mais ce n'est pas obligatoire, comme le montre le second exemple ci-dessus.

  > Note : Cette directive est destiné à vous aider dans votre développement en rendant facile la consultation de la description d'une fonction. Ne jamais l'utiliser sur un système de production (e.g. système connecté à Internet).

docref_ext string

  Voir aussi docref_root.

  > Note : La valeur de docref_ext doit commencer par un point '.'.

error_prepend_string string

  La chaîne à placer avant les messages d'erreur.

error_append_string string

  La chaîne à placer après les messages d'erreur.

error_log string

  Nom du fichier où seront enregistrées les erreurs. Le fichier doit être accessible en écriture par l'utilisateur exécutant le serveur web. Si la valeur spéciale syslog est utilisée, les erreurs seront envoyées au système d'historique du serveur. Sous Unix, cela correspond à syslog(3) et sous Windows NT, à l'historique d'événement. L'historique n'est pas supporté sous Windows 95. Voir aussi : syslog().

warn_plus_overloading boolean

  Si cette option est activée, PHP va afficher une alerte lorsque l'opérateur d'addition (+) est utilisé avec des chaînes de caractères. Cela peut aider à trouver les erreurs où le plus est utilisé comme opérateur de concaténation au lieu de point (.). Cette option n'existe pas en PHP 4.

# Constantes pré-définies

Les constantes listées ici sont toujours disponibles dans PHP.

> Note : Vous pouvez utiliser ces constantes dans le fichier `php.ini` mais pas hors de PHP, comme dans le fichier `httpd.conf`, où vous devez utiliser les valeurs de champs de bits.

Tableau 2. Erreurs et historique

Valeur | Constante | Description | Note
--- | --- | --- | ---
1 | `E_ERROR` (entier) | Les erreurs sont aussi affichées par défaut, et l'exécution du script est interrompue. Elles indiquent des erreurs qui ne peuvent pas être ignorées, comme des problèmes d'allocation de mémoire, par exemple. |
2 | `E_WARNING` (entier) | Les alertes sont affichées par défaut, mais n'interrompent pas l'exécution du script. Elles indiquent un problème qui doit être intercepté par le script durant l'exécution du script. Par exemple, appeler ereg() avec une regex invalide. |
4 | `E_PARSE` (entier) | Les erreurs d'analyse ne doivent être générées que par l'analyseur. Elles ne sont citées ici que dans le but d'être exhaustif. |
8 | `E_NOTICE` (entier) | Les notices ne sont pas affichées par défaut, et indiquent que le script a rencontré quelque chose qui peut être une erreur, mais peut aussi être un événement normal dans la vie du script. Par exemple, essayer d'accéder à une valeur qui n'a pas été déclarée, ou appeler stat() sur un fichier qui n'existe pas. |
16 | `E_CORE_ERROR` (entier) | Elles sont similaires aux erreurs `E_ERROR`, mais elles sont générées par le code de PHP. Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
32 | `E_CORE_WARNING` (entier) | Elles sont similaires à `E_WARNING`, mais elles sont générées par le code de PHP. Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
64 | `E_COMPILE_ERROR` (entier) | Elles sont similaires à `E_ERROR`, mais elles sont générées par Zend Scripting Engine. Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
128 | `E_COMPILE_WARNING` (entier) | Elles sont similaires à `E_WARNING`, mais elles sont générées par Zend Scripting Engine. Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
256 | `E_USER_ERROR` (entier) | `E_USER_ERROR` est comparable à `E_ERROR`. Elle est générée en PHP par l'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
512 | `E_USER_WARNING` (entier) | `E_USER_WARNING` est comparable à `E_WARNING`. Elle est générée en PHP par l'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
1024 | `E_USER_NOTICE` (entier) | `E_USER_WARNING` est comparable à `E_NOTICE`. Elle est générée en PHP parl'utilisation de la fonction trigger_error(). Les fonctions ne doivent pas générer ce genre d'erreur. | depuis PHP 4 seulement
2047 | `E_ALL` (entier) | Toutes les erreurs et alertes supportées sauf le niveau `E_STRICT`. |
2048 | `E_STRICT` (entier) | Notices au moment de l'exécution. Permet d'obtenir des suggestions de PHP pour modifier votre code, assurant ainsi une meilleure interopérabilité et compatibilité de celui-ci. | PHP 5 seulement.

Les valeurs ci-dessus (numérique ou symbolique) sont utilisées pour constituer des champs de bits, qui spécifient le niveau de rapport d'erreur. Vous pouvez utiliser les opérateurs de bits pour combiner ces valeurs pour en faire des masques qui filtrent certaines erreurs. Notez bien que seuls '|', '~', '!', '^' et '&' seront compris dans le fichier `php.ini`, et que aucun opérateur logique ne sera compris en `php3.ini`.

# Exemples

Ci-dessous, vous trouverez un exemple de gestion des erreurs par PHP. Il y est défini un gestionnaire d'erreur, qui enregistre les informations dans un fichier (au format XML), et envoie un courriel au développeur si l'erreur est critique.

Exemple 1. Gestion d'erreurs avancées en PHP
`<?php // Nous allons faire notre propre gestion error_reporting(0); // Fonction spéciale de gestion des erreurs function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) { // Date et heure de l'erreur $dt = date("Y-m-d H:i:s (T)"); // Définit un tableau associatif avec les chaînes d'erreur // En fait, les seuls niveaux qui nous interessent // sont E_WARNING, E_NOTICE, E_USER_ERROR, // E_USER_WARNING et E_USER_NOTICE $errortype = array ( E_ERROR => "Erreur", E_WARNING => "Alerte", E_PARSE => "Erreur d'analyse", E_NOTICE => "Note", E_CORE_ERROR => "Core Error", E_CORE_WARNING => "Core Warning", E_COMPILE_ERROR => "Compile Error", E_COMPILE_WARNING => "Compile Warning", E_USER_ERROR => "Erreur spécifique", E_USER_WARNING => "Alerte spécifique", E_USER_NOTICE => "Note spécifique", E_STRICT => "Runtime Notice" ); // Les niveaux qui seront enregistrés $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE); $err = "<errorentry>\n"; $err .= "\t<datetime>" . $dt . "</datetime>\n"; $err .= "\t<errornum>" . $errno . "</errornum>\n"; $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n"; $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n"; $err .= "\t<scriptname>" . $filename . "</scriptname>\n"; $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n"; if (in_array($errno, $user_errors)) { $err .= "\t<vartrace>".wddx_serialize_value($vars,"Variables")."</vartrace>\n"; } $err .= "</errorentry>\n\n"; // sauvegarde de l'erreur, et mail si c'est critique error_log($err, 3, "/usr/local/php4/error.log"); if ($errno == E_USER_ERROR) { mail("phpdev@example.com","Critical User Error",$err); } } function distance($vect1, $vect2) { if (!is_array($vect1) || !is_array($vect2)) { trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR); return NULL; } if (count($vect1) != count($vect2)) { trigger_error("Vectors need to be of the same size", E_USER_ERROR); return NULL; } for ($i=0; $i<count($vect1); $i++) { $c1 = $vect1[$i]; $c2 = $vect2[$i]; $d = 0.0; if (!is_numeric($c1)) { trigger_error("Coordinate $i in vector 1 is not a number, using zero", E_USER_WARNING); $c1 = 0.0; } if (!is_numeric($c2)) { trigger_error("Coordinate $i in vector 2 is not a number, using zero", E_USER_WARNING); $c2 = 0.0; } $d += $c2*$c2 - $c1*$c1; } return sqrt($d); } $old_error_handler = set_error_handler("userErrorHandler"); // constante non définie, qui génère une alerte $t = I_AM_NOT_DEFINED; // définition de quelques vecteurs $a = array (2, 3, "foo"); $b = array (5.5, 4.3, -1.6); $c = array (1, -3); // génère une erreur utilisateur $t1 = distance ($c, $b)."\n"; // génère une erreur utilisateur $t2 = distance ($b, "i am not an array")."\n"; // Génère une alerte $t3 = distance ($a, $b)."\n"; ?>`

# Voir aussi

Voir aussi syslog().

Précédent | Sommaire | Suivant
xptr_new_context | Niveau supérieur | debug_backtrace