doc-fr/reference/mail/functions/mail.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0c9c2dd669fe9395eaa73d487fbd160f9057429a Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.mail" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>mail</refname>
  <refpurpose>Envoi de mail</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>mail</methodname>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam><type>string</type><parameter>message</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>string</type></type><parameter>additional_headers</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>additional_params</parameter><initializer>""</initializer></methodparam>
  </methodsynopsis>
  <para>
   Envoie un mail.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       Le ou les destinataires du mail.
      </para>
      <para>
       Le formatage de cette chaîne doit correspondre avec la 
       <link xlink:href="&url.rfc;2822">RFC 2822</link>. Voici quelques exemples :
       <simplelist>
        <member>destinataire@example.com</member>
        <member>destinataire@example.com, autre_destinataire@example.com</member>
        <member>Destinataire &lt;destinataire@example.com&gt;</member>
        <member>Destinataire &lt;destinataire@example.com&gt;, Autre destinataire &lt;autre_destinataire@example.com&gt;</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Sujet du mail à envoyer.
      </para>
      <caution>
       <para>
        Le sujet doit satisfaire à la <link xlink:href="&url.rfc;2047">RFC 2047</link>.
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>message</parameter></term>
     <listitem>
      <para>
       Message à envoyer.
      </para>
      <para>
       Chaque ligne doit être séparée par un caractère <literal>CRLF</literal>
       (<literal>\r\n</literal>). Les lignes ne doivent pas comporter plus de 70 caractères.
      </para>
      <caution>
       <para>
        (Windows uniquement) Lorsque PHP discute directement avec un serveur
        SMTP, si un point est trouvé en début de ligne, il sera supprimé.
        Pour éviter ce comportement, remplacez ces occurrences par un double
        point.
        <programlisting role="php">
<![CDATA[
<?php
     $text = str_replace("\n.", "\n..", $text);
?>
]]>
        </programlisting>
       </para>
      </caution>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_headers</parameter> (optionnel)</term>
     <listitem>
      <para>
       <type>String</type> ou <type>array</type> à insérer à la fin des en-têtes du mail.
      </para>
      <para>
       Ce paramètre est typiquement utilisé pour ajouter des en-têtes supplémentaires
       (From, Cc et Bcc). Les en-têtes supplémentaires doivent être
       séparés par un caractère <literal>CRLF</literal> (<literal>\r\n</literal>).
       Si des données externes sont utilisées pour composer cet en-tête, elles doivent
       être d'abord nettoyées afin de ne pas injecter des données non désirées
       dans les en-têtes.
      </para>
      <para>
       Si un <type>array</type> est passé, ses clés sont les noms d'en-tête et 
       ses valeurs sont les valeurs d'en-tête respectives.
      </para>
      <note>
       <para>
        Avant PHP 5.4.42 et 5.5.27, respectivement, 
        <parameter>additional_headers</parameter> n'avait pas de protection
        d'injection en-tête de messagerie. Par conséquent, les utilisateurs 
        doivent s'assurer que les en-têtes spécifiés sont sûrs et contiennent 
        uniquement des en-têtes. C'est à dire ne jamais démarrer le corps du 
        courrier en mettant plusieurs sauts.
       </para>
      </note> 
      <note>
       <para>
        Lors de l'envoi d'un mail, le mail <emphasis>doit</emphasis>
        contenir un en-tête <literal>From</literal>. Il peut être
        défini par le paramètre <parameter>additional_headers</parameter>,
        ou un par défaut peut être défini dans le &php.ini;.
       </para>
       <para>
        Ne pas faire ceci causera un message d'erreur similaire à
        <literal>Warning: mail(): "sendmail_from" not
         set in php.ini or custom "From:" header missing</literal>.
        L'en-tête <literal>From</literal> définit également l'en-tête
        <literal>Return-Path</literal> lors de l'envoi direct via SMTP (Windows
        uniquement).
       </para>
      </note>
      <note>
       <para>
        Si le message n'est pas reçu, essayez d'utiliser uniquement un caractère
        <literal>LF</literal> (<literal>\n</literal>).
        Quelques agents de transfert de mail Unix (par exemple
        <link xlink:href="&url.qmail;">qmail</link>)
        remplacent le caractère <literal>LF</literal> par le 
        caractère <literal>CRLF</literal> automatiquement
        (ce qui revient à doubler le caractère <literal>CR</literal>
        si le caractère <literal>CRLF</literal> est utilisé).
        Ceci doit être un dernier recours car cela ne correspond pas
        à la <link xlink:href="&url.rfc;2822">RFC 2822</link>.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>additional_params</parameter> (optionnel)</term>
     <listitem>
      <para>
       Le paramètre <parameter>additional_params</parameter>
       peut être utilisé pour passer des drapeaux additionnels comme options
       à la ligne de commande configurée pour être utilisée pour envoyer les
       mails en utilisant le paramètre de configuration <literal>sendmail_path</literal>.
       Par exemple, ceci peut être utilisé pour définir l'adresse
       d'expéditeur de l'enveloppe lors de l'utilisation de sendmail avec l'option 
       <literal>-f</literal>.
      </para>
      <para>
       Ce paramètre est échappé par la fonction <function>escapeshellcmd</function> en interne
       afin de prévenir l'exécution d'une commande. La fonction <function>escapeshellcmd</function>
       empêche l'exécution d'une commande, mais autorise l'ajout de paramètres supplémentaires.
       Pour des raisons de sécurité, il est recommandé pour l'utilisateur de nettoyer ce paramètre
       afin d'éviter l'ajout de paramètres non désirés à la commande shell.
      </para>
      <para>
       Depuis que la fonction <function>escapeshellcmd</function> est appliquée automatiquement,
       quelques caractères autorisés dans les adresses emails par les RFCs d'internet ne peuvent
       plus être utilisés. La fonction <function>mail</function> ne peut autoriser ces caractères,
       aussi, dans les programme où leur utilisation est nécessaire, vous devriez utiliser
       une méthode alternative pour l'envoi des emails (comme l'utilisation d'un framework
       ou d'une librairie.
      </para>
      <para>
       L'utilisateur sous lequel tourne le serveur web doit être ajouté en tant qu'utilisateur de confiance
       dans la configuration de sendmail afin que l'en-tête <literal>X-Warning</literal>
       ne soit pas ajouté au message lorsque l'expéditeur de l'enveloppe (-f) est
       défini en utilisant cette méthode. Pour les utilisateurs de sendmail, ce fichier est
       <filename>/etc/mail/trusted-users</filename>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Retourne &true; si le mail a été accepté pour livraison, &false; sinon.
  </para>
  <para>
   Il est important de noter que ce n'est pas parce que le mail a été accepté pour livraison
   qu'il arrivera à destination.
  </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>7.2.0</entry>
       <entry>
        Le paramètre <parameter>additional_headers</parameter> accepte maintenant
        les <type>array</type>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Envoi d'un mail</title>
    <para>
     Utilisation de la fonction <function>mail</function> pour envoyer un mail simple :
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Le message
$message = "Line 1\r\nLine 2\r\nLine 3";

// Dans le cas où nos lignes comportent plus de 70 caractères, nous les coupons en utilisant wordwrap()
$message = wordwrap($message, 70, "\r\n");

// Envoi du mail
mail('caffeinated@example.com', 'Mon Sujet', $message);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envoi d'un mail avec des en-têtes supplémentaires</title>
    <para>
     L'ajout d'en-têtes simples, spécifiant au MUA les adresses
     <literal>"From"</literal> et <literal>"Reply-To"</literal> :
    </para>
    <programlisting role="php">
<![CDATA[
<?php
     $to      = 'personne@example.com';
     $subject = 'le sujet';
     $message = 'Bonjour !';
     $headers = 'From: webmaster@example.com' . "\r\n" .
     'Reply-To: webmaster@example.com' . "\r\n" .
     'X-Mailer: PHP/' . phpversion();

     mail($to, $subject, $message, $headers);
 ?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envoi d'un mail avec un <type>array</type> d'en-têtes supplémentaires</title>
    <para>
     Cet exemple envoie le même courrier que l'exemple ci-dessus, mais passe 
     les en-têtes supplémentaires en tant que tableau (disponible depuis PHP 
     7.2.0).
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$to      = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = array(
    'From' => 'webmaster@example.com',
    'Reply-To' => 'webmaster@example.com',
    'X-Mailer' => 'PHP/' . phpversion()
);

mail($to, $subject, $message, $headers);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envoi d'un mail avec un paramètre de ligne de commande additionnel</title>
    <para>
     Le paramètre <parameter>additional_params</parameter>
     peut être utilisé pour passer un paramètre additionnel au programme configuré
     à être utilisé pour envoyer les mails en utilisant <literal>sendmail_path</literal>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
     mail('personne@example.com', 'le sujet', 'le message', null,
     '-fwebmaster@example.com');
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Envoi de mail HTML</title>
    <para>
     Il est également possible d'envoyer des mails HTML avec la fonction
     <function>mail</function>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
     // Plusieurs destinataires
     $to  = 'johny@example.com, sally@example.com'; // notez la virgule

     // Sujet
     $subject = 'Calendrier des anniversaires pour Août';

     // message
     $message = '
     <html>
      <head>
       <title>Calendrier des anniversaires pour Août</title>
      </head>
      <body>
       <p>Voici les anniversaires à venir au mois d\'Août !</p>
       <table>
        <tr>
         <th>Personne</th><th>Jour</th><th>Mois</th><th>Année</th>
        </tr>
        <tr>
         <td>Josiane</td><td>3</td><td>Août</td><td>1970</td>
        </tr>
        <tr>
         <td>Emma</td><td>26</td><td>Août</td><td>1973</td>
        </tr>
       </table>
      </body>
     </html>
     ';

     // Pour envoyer un mail HTML, l'en-tête Content-type doit être défini
     $headers[] = 'MIME-Version: 1.0';
     $headers[] = 'Content-type: text/html; charset=iso-8859-1';

     // En-têtes additionnels
     $headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
     $headers[] = 'From: Anniversaire <anniversaire@example.com>';
     $headers[] = 'Cc: anniversaire_archive@example.com';
     $headers[] = 'Bcc: anniversaire_verif@example.com';

     // Envoi
     mail($to, $subject, $message, implode("\r\n", $headers));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <note>
    <para>
     Si vous prévoyez d'envoyer des mails HTML ou autrement plus complexes,
     il est recommandé d'utiliser le paquet PEAR <link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</link>.
    </para>
   </note>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    L'implémentation SMTP (uniquement sous Windows) de la fonction
    <function>mail</function> diffère de manière significative avec
    l'implémentation de sendmail. Tout d'abord, il n'utilise
    pas un programme local pour composer les messages, mais opère uniquement et 
    directement sur les sockets, ce qui signifie qu'un <literal>MTA</literal>
    est nécessairement à l'écoute sur un socket du réseau (qui peut être soit
    sur le réseau local ou sur une machine distante).
   </para>
   <para>
    Deuxièmement, les en-têtes personnalisés comme
    <literal>From:</literal>,
    <literal>Cc:</literal>,
    <literal>Bcc:</literal> et
    <literal>Date:</literal> ne sont
    <emphasis role="strong">pas</emphasis> interprétés par le
    <literal>MTA</literal> dans un premier temps, mais sont analysés par PHP.
   </para>
   <para>
    De plus, le paramètre <parameter>to</parameter> ne doit pas être une adresse
    sous la forme <literal>"Quelque chose &lt;quelqu_un@example.com&gt;"</literal>. 
    La commande mail n'analysera pas correctement ceci lors de la discussion
    avec le MTA.
   </para>
  </note>

  <note>
   <para>
    Il est important de noter que la fonction <function>mail</function> 
    n'est pas conseillée pour traiter de gros volumes de mails dans une boucle.
    Cette fonction ouvre et ferme un socket SMTP pour chaque mail, ce qui n'est
    pas très efficace.
   </para>
   <para>
    Pour envoyer de gros volumes de mails, reportez-vous aux paquets
    <link xlink:href="&url.pear.package;Mail">PEAR::Mail</link> et
    <link xlink:href="&url.pear.package;Mail_Queue">PEAR::Mail_Queue</link>.
   </para>
  </note>

  <note>
   <para>
    Les RFC suivantes peuvent être utiles :
    <link xlink:href="&url.rfc;1896">RFC 1896</link>,
    <link xlink:href="&url.rfc;2045">RFC 2045</link>,
    <link xlink:href="&url.rfc;2046">RFC 2046</link>,
    <link xlink:href="&url.rfc;2047">RFC 2047</link>,
    <link xlink:href="&url.rfc;2048">RFC 2048</link>,
    <link xlink:href="&url.rfc;2049">RFC 2049</link> et
    <link xlink:href="&url.rfc;2822">RFC 2822</link>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mb_send_mail</function></member>
    <member><function>imap_mail</function></member>
    <member><link xlink:href="&url.pear.package;Mail">PEAR::Mail</link></member>
    <member><link xlink:href="&url.pear.package;Mail_Mime">PEAR::Mail_Mime</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
-->