set-error-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 21ce7d7f4f9f6f241f3e09e7f0a5be5c504d90d2 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>set_error_handler</refname>
  <refpurpose>Spécifie une fonction utilisateur comme gestionnaire d'erreurs</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>callable</type><type>null</type></type><methodname>set_error_handler</methodname>
   <methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>set_error_handler</function> choisit la fonction utilisateur
   <parameter>callback</parameter> pour gérer les erreurs dans un script.
  </para>
  <para>
   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 <function>trigger_error</function>).
  </para>
  <para>
   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 <parameter>error_levels</parameter> à moins que la fonction
   de rappel retourne &false;.
   Les paramètres de la fonction <function>error_reporting</function> 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 la configuration de.
   <link linkend="ini.error-reporting">error_reporting</link> et
   faire réagir la fonction de gestion des erreurs en fonction.
  </para>

  <para>
   Notez aussi que c'est la responsabilité du gestionnaire d'erreurs d'arrêter
   l'exécution du script si nécessaire en appelant la fonction <function>exit</function>. 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.
  </para>
  <para>
   Les types d'erreur suivants ne peuvent pas être gérés avec cette fonction : 
   <constant>E_ERROR</constant>, <constant>E_PARSE</constant>,
   <constant>E_CORE_ERROR</constant>, <constant>E_CORE_WARNING</constant>,
   <constant>E_COMPILE_ERROR</constant>,
   <constant>E_COMPILE_WARNING</constant> indépendamment d'où elles sont levées,
   ainsi que la plupart des
   <constant>E_STRICT</constant> du fichier dans lequel 
   <function>set_error_handler</function> est appelé.
  </para>
  <para>
   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é.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Si &null; est fournie le gestionnaire est réinitialisé à son statut par défaut.
       Sinon, le gestionnaire est une fonction de rappel avec la signature suivante :
      </para>
      <para>
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>handler</replaceable></methodname>
        <methodparam><type>int</type><parameter>errno</parameter></methodparam>
        <methodparam><type>string</type><parameter>errstr</parameter></methodparam>
        <methodparam choice="opt"><type>string</type><parameter>errfile</parameter></methodparam>
        <methodparam choice="opt"><type>int</type><parameter>errline</parameter></methodparam>
        <methodparam choice="opt"><type>array</type><parameter>errcontext</parameter></methodparam>
       </methodsynopsis>
       <variablelist>
        <varlistentry>
         <term><parameter>errno</parameter></term>
         <listitem>
          <simpara>
           Le premier paramètre <parameter>errno</parameter>, sera passé le
           niveau d'erreur, sous la forme d'un entier.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errstr</parameter></term>
         <listitem>
          <simpara>
           Le second paramètre <parameter>errstr</parameter>, sera passé le
           message d'erreur, sous forme de chaîne.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errfile</parameter></term>
         <listitem>
          <simpara>
           Si la fermeture accepte un troisième paramètre, <parameter>errfile</parameter>,
           il sera passé le nom du fichier dans lequel l'erreur a été identifiée, sous forme de chaîne.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errline</parameter></term>
         <listitem>
          <simpara>
           Si la fermeture accepte un quatrième paramètre, <parameter>errline</parameter>,
           il sera passé le numéro de ligne à laquelle l'erreur a été identifiée, sous la forme d'un entier.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><parameter>errcontext</parameter></term>
         <listitem>
          <simpara>
           Si la fermeture accepte un cinquième paramètre, <parameter>errcontext</parameter>,
           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, <parameter>errcontext</parameter>
           contient un tableau avec toutes les variables qui existaient lorsque
           l'erreur a été déclenchée.
           Les gestionnaires d'erreurs utilisateur ne doit pas modifier le contexte d'erreur.
          </simpara>
          <warning xmlns="http://docbook.org/ns/docbook">
           <simpara>
            Ce paramètre est <emphasis>OBSOLÈTE</emphasis> à partir de PHP 7.2.0,
            et <emphasis>SUPPRIMÉ</emphasis> à partir de PHP 8.0.0. Si la
            fonction définie ce paramètre sans valeur par défaut, une erreur de
            "too few arguments" sera levée lors de son appel.
           </simpara>
          </warning>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
      <para>
       Si la fonction retourne &false;, alors le gestionnaire d'erreurs normal continue.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>error_levels</parameter></term>
     <listitem>
      <para>
       Sert de masque pour appeler la fonction 
       <parameter>callback</parameter> de la même façon que l'option de
       configuration <link linkend="ini.error-reporting">error_reporting</link>
       contrôle les erreurs qui sont affichées. Sans le masque,
       <parameter>callback</parameter> sera appelé pour toutes les erreurs,
       quelle que soit la valeur de
       <link linkend="ini.error-reporting">error_reporting</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne le dernier gestionnaire d'erreurs (s'il existe) sous forme de <type>callable</type>.  
   Si le gestionnaire d’erreurs interne est utilisé, &null; est retourné.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.0.0</entry>
       <entry>
        <parameter>errcontext</parameter> a été supprimé, et ne sera plus passé aux fermetures utilisateur.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        <parameter>errcontext</parameter> est devenu obsolète.
        L'usage de ce paramètre émet une notice <constant>E_DEPRECATED</constant>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Gestionnaire d'erreurs avec <function>set_error_handler</function> et 
     <function>trigger_error</function></title>
    <para>
     L'exemple ci-dessous illustre l'interception d'erreurs internes avec
     génération d'erreur et son exploitation dans une fonction utilisateur :
    </para>
    <programlisting role="php">
<![CDATA[
<?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 gestionaire 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) for x <= 0 is undefined, you used: 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";
/* Valeur à la position $pos n'est pas un nombre, utilisation de 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 tablau", 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, vous utilisez : scale = $scale" */
$d = scale_by_log($a, -2.5);
var_dump($d); // Jamais atteint
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
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 de 0 (zéro)<br />
Array
(
    [0] => 2.2894597716988
    [1] => 3.4341896575482
    [2] => 0
    [3] => 6.2960143721717
    [4] => 49.566804057279
    [5] => 24.165247890281
)
----
vector c - an warning
<b>Mon ALERTE</b> [512] Entrée incorrect, tableau de valeurs attendu<br />
NULL
----
vector d - fatal error
<b>Mon ERREUR</b> [256] log(x) for x <= 0 est indéfini, vous utilisez : scale = -2.5<br />
Erreur fatale sur la ligne 36 dans le fichier trigger_error.php, PHP 4.0.2 (Linux)<br />
Abandon...<br />
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><classname>ErrorException</classname></member>
    <member><function>error_reporting</function></member>
    <member><function>restore_error_handler</function></member>
    <member><function>get_error_handler</function></member>
    <member><function>trigger_error</function></member>
    <member><link linkend="errorfunc.constants">Constantes de niveau d'erreur</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->