[PHP-DOC] cvs: phpdoc /fr/pear pear.xml

[Damien Seguy]

dams            Fri Mar 30 00:51:49 2001 EDT

  Added files:                 
    /phpdoc/fr/pear     pear.xml 
  Log:
  Added PEAR and translated.
  

Index: phpdoc/fr/pear/pear.xml
+++ phpdoc/fr/pear/pear.xml
 <reference id="ref.pear">
  <title>Manuel de r&eacute;f&eacute;rence PEAR</title>
  <titleabbrev>PEAR</titleabbrev>
  <partintro>
   <simpara>
    Ce chapitre contient la documentation de r&eacute;f&eacute;rence des composants
    PEAR, qui sont distribu&eacute; avec PHP. Une bonne connaissances des
    m&eacute;canismes <link linkend="language.oop">objets</link> est 
    n&eacute;cessaire.
   </simpara>
  </partintro>
  <refentry id="class.pear">
   <refnamediv>
    <refname>PEAR</refname>
    <refpurpose>Classe de base PEAR</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <synopsis>require_once "PEAR.php";</synopsis>
    <synopsis>class <replaceable>classname</replaceable> extends 
<classname>PEAR</classname> { ... }</synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Description</title>
    <simpara>
     La classe de base PEAR fournit les fonctionnalit&eacute;s qui sont 
utilis&eacute;es
     par la plus part des classes PEAR. Normalement, vous n'avez pas &agrave; 
     utiliser cette classe directement : il vous suffit d'en h&eacute;riter.
    </simpara>
    <para>
     Les fonctionnalit&eacute;s marquantes sont : 
     <itemizedlist>
      <listitem>
       <simpara>Fonction de fin de requ&ecirc;te</simpara>
      </listitem>
      <listitem>
       <simpara>Gestion des erreurs</simpara>
      </listitem>
     </itemizedlist>
    </para>
    <refsect2>
     <title>Fonction de fin de requ&ecirc;te</title>
     <simpara>
      Si vous fa&icirc;tes h&eacute;riter de la classe <classname>PEAR</classname>,
      une classe appel&eacute;e <replaceable>NomClasse</replaceable>, vous pouvez
      d&eacute;finir une m&eacute;thode appel&eacute;e 
<literal>_<replaceable>ClassName</replaceable></literal>
      (le nom de la classe pr&eacute;c&eacute;d&eacute; d'un soulign&eacute;), qui 
sera appel&eacute;e
      lorsque le script prend fin. Ce n'est pas un destructeur, car
      vous pouvez d&eacute;truire un objet avec cette m&eacute;thode, mais le 
destructeur
      sera quand m&ecirc;me appel&eacute;. C'est une fonction de callback, qui
      intervient lorsque le script prend fin. Voyez 
      <link linkend="example.pear.destructors">l'exemple</link>.
     </simpara>
    </refsect2>
    <refsect2>
     <title>Gestion des erreurs</title>
     <simpara>
      La classe de base PEAR fournit aussi un moyen de manipuler des
      erreurs plus complexes qu'un simple bool&eacute;en ou entier. Une
      erreur PEAR est un objet qui est une instance de la classe
      <classname>PEAR_Error</classname>, ou d'une de ses sous-classes.
     </simpara>
     <simpara>
      Une des &eacute;xigences de conception des erreurs PEAR est qu'il ne
      faut pas forcer l'affichage d'erreurs, mais plut&ocirc;t de fournir
      les outils pour les afficher, tout en laissant &agrave; l'utilisateur
      le choix de les utiliser. Cela permet de traiter correctement
      les erreurs, notamment si le format de sortie n'est pas HTML
      (par exemple WML ou XML).
     </simpara>
     <simpara>
      L'objet d'erreur peut &ecirc;tre configur&eacute; de nombreuses fa&ccedil;ons 
d&egrave;s
      sa cr&eacute;ation : affichage d'erreur, affichage d'erreur suivi
      de la fin du script, envoie d'une erreur PHP avec 
      <function>trigger_error</function>, appeler une fonction
      de traitement, ou rien du tout. Vous pouvez typiquement
      sp&eacute;cifier ces parm&egrave;tres d&egrave;s le constructeur de
      <classname>PEAR_Error</classname> : tous ces param&egrave;tres sont
      optionnel, et <classname>PEAR</classname> fournit un moyen de
      g&eacute;rer des valeurs par d&eacute;faut. Voyez les 
      <link linkend="example.pear.error1">exemples d'erreurs PEAR</link>,
      pour avoir une illustration, et la documentation de 
      <classname>PEAR_Error</classname> pour plus de d&eacute;tails.
     </simpara>
    </refsect2>
   </refsect1>
   <refsect1 id="example.pear.destructors">
    <title>Exemples</title>
    <para>
     Les exemples ci-dessus montre comment utiliser les
     simili destructeurs, pour impl&eacute;menter une classe qui g&egrave;re le
     contenu d'un fichier, ajoute des donn&eacute;es, et sauve le tout
     &agrave; la fin du script.
     <example>
      <title>Les simili destructeurs de PEAR</title>
      <programlisting role="php">
&lt;?php
require_once "PEAR.php";

class FileContainer extends PEAR
{
    var $file = '';
    var $contents = '';
    var $modified = 0;
    
    function FileContainer($file)
    {
        $this->PEAR(); // cette ligne appelle le constructeur p&egrave;re
        $fp = fopen($file, "r");
        if (!is_resource($fp)) {
            return;
        }
        while (!empty($data = fread($fp, 2048))) {
            $this->contents .= $data;
        }
        fclose($fp);
    }

    function append($str)
    {
        $this->contents .= $str;
        $this->modified++;
    }

    // le simili-destructeur est nomm&eacute; d'apr&egrave;s le nom de la classe
    // mais avec un soulign&eacute; devant.
    function _FileContainer()
    {
        if ($this->modified) {
            $fp = fopen($this->file, "w");
            if (!is_resource($fp)) {
                return;
            }
            fwrite($fp, $this->contents);
            fclose($fp);
        }
    }
}

$fileobj = new FileContainer("testfile");
$fileobj->append("Ceci se termine &agrave; la fin du fichier\n");

// Lorsque le script est termin&eacute; et que PHP s'arr&ecirc;te,
// le simili destructeur de $fileobj est appel&eacute;, et 
// met &agrave; jour les informations sur le disque
?&gt;
      </programlisting>
     </example>
     <note>
      <simpara>
       Les simili destructeurs de PEAR utilisent les fonctions de
       fin de script de PHP (<function>register_shutdown_function</function>), 
       et vous ne pourrez rien afficher dans ces fonctions, si vous
       utilisez un serveur web. En ligne de commande, toutefois, 
       l'affichage se fera. C'est comme ca. 
      </simpara>
     </note>
    </para>
    <simpara>
     L'exemple suivant montre diff&eacute;rentes fa&ccedil;ons d'utiliser le 
     m&eacute;canisme d'erreur de PHP.
    </simpara>
    <para>
     <example id="example.pear.error1">
      <title>Exemple d'erreurs PEAR(1)</title>
      <programlisting role="php">
&lt;?php
function mysockopen($host = "localhost", $port = 8090)
{
    $fp = fsockopen($host, $port, $errno, $errstr);
    if (!is_resource($fp)) {
        return new PEAR_Error($errstr, $errno);
    }
    return $fp;
}

$sock = mysockopen();
if (PEAR::isError($sock)) {
    print "mysockopen error: ".$sock->getMessage()."&lt;BR>\n"
}
?&gt;
      </programlisting>
     </example>
    </para>
    <simpara>
     Cet exemple illustre une fonction de <function>fsockopen</function>
     qui retourne le code d'erreur et, au cas &eacute;ch&eacute;ant, le message
     retourn&eacute; par le serveur. Notez que <function>pear->iserror</function>
     sert &agrave; savoir si une valeur est une erreur PEAR.
    </simpara>
    <simpara>
     Le mode op&eacute;ratoire de PEAR_Error dans cet exemple est de
     simplement retourner l'objet d'erreur, et laisser le reste
     au d&eacute;veloppeur. C'est le mode par d&eacute;faut.
    </simpara>
    <simpara>
     Dans le prochain exemple, on utilise d'autres modes : 
    </simpara>
    <para>
     <example id="example.pear.error2">
      <title>PEAR error example (2)</title>
      <programlisting role="php">
&lt;?php
class TCP_Socket extends PEAR
{
    var $sock;

    function TCP_Socket()
    {
        $this->PEAR();
    }

    function connect($host, $port)
    {
        $sock = fsockopen($host, $port, $errno, $errstr);
        if (!is_resource($sock)) {
            return $this->raiseError($errstr, $errno);
        }
    }
}

$sock = new TCP_Socket;
$sock->setErrorHandling(PEAR_ERROR_DIE);
$sock->connect("localhost", 8090);
print "Toujours connect&eacute;&lt;BR>\n";
?&gt;
</programlisting>
     </example>
    </para>
    <simpara>
     Ici, le mode par d&eacute;faut est <constant>PEAR_ERROR_DIE</constant>, et comme
     on ne sp&eacute;cifie aucun mode d'erreur dans l'appel &agrave; 
     (ce devrait &ecirc;tre le troisi&egrave;me argument), 
     raiseError utilise le mode par d&eacute;faut, et termine le script
     si <function>fsockopen</function> &eacute;choue.
    </simpara>
   </refsect1>
  </refentry>
  <refentry id="class.pear-error">
   <refnamediv>
    <refname>PEAR_Error</refname>
    <refpurpose>M&eacute;chanisme de base des erreurs PEAR</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
    <synopsis>$err = new <classname>PEAR_Error</classname>($msg);</synopsis>
   </refsynopsisdiv>
   <refsect1>
    <title>Modes d'erreurs</title>
    <para>
     Un objet d'erreur a un mode d'op&eacute;ration, qui peut &ecirc;tre 
     l'une des constantes suivantes : 
     <variablelist id="pear.error-modes">
      <varlistentry id="constant.pear-error-return">
       <term>PEAR_ERROR_RETURN</term>
       <listitem>
        <simpara>
         Retourne simplement l'objet, et ne fait rien de
         sp&eacute;cial dans le constructeur de PEAR_Error.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-print">
       <term>PEAR_ERROR_PRINT</term>
       <listitem>
        <simpara>
         Affiche le message d'erreur dans le constructeur. L'ex&eacute;cution
         n'est pas interrompue.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-trigger">
       <term>PEAR_ERROR_TRIGGER</term>
       <listitem>
        <simpara>
         Utilise la fonction <function>trigger_error</function> pour envoyer
         une erreur interne &agrave; PHP. L'ex&eacute;cution est interrompue si
         vous avez d&eacute;finit vos propres gestionnaires d'erreurs, ou si
         vous avez utilisez le niveau d'erreur E_USER_ERROR.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-die">
       <term>PEAR_ERROR_DIE</term>
       <listitem>
        <simpara>
         Affiche le message d'erreur et termine le script. 
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry id="constant.pear-error-callback">
       <term>PEAR_ERROR_CALLBACK</term>
       <listitem>
        <simpara>
         Utilise une fonction utilisateur pour g&eacute;rer les 
         erreurs. L'ex&eacute;cution s'arr&ecirc;te.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>
   <refsect1>
    <title>Propri&eacute;t&eacute;s</title>
    <simpara></simpara>
   </refsect1>
   <refsect1>
    <title>M&eacute;thodes</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef><function>pear_error::pear_error</function></funcdef>
      <paramdef>
       <parameter><optional>message</optional></parameter>
       <parameter><optional>code</optional></parameter>
       <parameter><optional>mode</optional></parameter>
       <parameter><optional>options</optional></parameter>
       <parameter><optional>userinfo</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <refsect2>
     <title>Description</title>
     <para>
      Constructeur PEAR_Error.  Param&eacute;tres :
      <variablelist>
       <varlistentry>
        <term>message</term>
        <listitem>
         <simpara>
          message d'erreur. Par d&eacute;faut, <literal>"unknown error"</literal> 
          ("erreur inconnue").
         </simpara>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>code</term>
        <listitem>
         <simpara>
          code d'erreur (optionnel)
         </simpara>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>mode</term>
        <listitem>
         <simpara>
          Mode d'op&eacute;ration.  Voir les <link
          linkend="pear.error-modes">modes d'erreur</link>, pour 
          plus de d&eacute;tails.
         </simpara>
        </listitem>
       </varlistentry>
       <varlistentry>
        <term>options</term>
        <listitem>
         <simpara>
          Si le mode peut avoir des options, utilisez ce param&egrave;tre.
          Actuellement, seules les valeurs de "trigger" et "callback" 
          utilisent ce param&egrave;tre. Pour le mode trigger,
          ce param&egrave;tre peut valoir <constant>E_USER_NOTICE</constant>,
          <constant>E_USER_WARNING</constant> ou
          <constant>E_USER_ERROR</constant>.  Pour le mode callback,
          ce param&egrave;tre doit contenir soit le nom de la fonction de
          callback (cha&icirc;ne), soit un tableau &agrave; deux 
&eacute;l&eacute;ments (objet,
          cha&icirc;ne) repr&eacute;sentant un objet et une m&eacute;thode &agrave; 
appeler.
         </simpara>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </refsect2>
   </refsect1>
  </refentry>
 </reference>
<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->