[[PageOutline(2, Sommaire)]]

= Wamailer 3.0 =

== Présentation ==

Qu’est-ce que Wamailer ? Une '''librairie''' composée de plusieurs classes écrites en [http://www.php.net/ PHP] et permettant de générer et envoyer des emails.[[BR]]
Wamailer respecte du mieux possible les différentes RFC décrivant la syntaxe des emails.[[BR]]
Wamailer est distribué sous [http://www.gnu.org/licenses/lgpl.html licence LGPL].

== Fonctionnalités ==

 * Support des emails HTML et multi-formats (texte ''et'' HTML)
 * Destinataires multiples directs, en CC ou BCC
 * Support des attachements de fichiers
 * Support des images embarquées (applicable aussi bien à d’autres types de fichier)
 * Support des encodages de transfert 8bit, quoted-printable, base64 et binary
 * Support d’[http://www.unicode.org/ Unicode] (avec l’UTF-8 seulement)
 * Ajout et modification d’entêtes d’email
 * Reformatage des messages sur la limite de 78 caractères par ligne (word wrap)
 * Support SMTP basique
 * Support des appels systèmes à Sendmail ou compatible
 * Support expérimental d’OpenPGP/MIME (voir la page OpenPgp)
 * Fonctionne également sur les hébergements Online (fonction email() spécifique)
 * Fonctionnel sur toutes plateformes

== Exemples ==

La version 3.0 est une version complètement réécrite en PHP5.[[BR]]
« Pourquoi ? La version actuelle (2.x) semble bien fonctionner », me direz-vous. Certes, mais on ne peut pas nier que le code soit un peu vieillot. J’ai commencé à développer Wamailer en 2002 et la version courante, modulo quelques corrections au cours des ans et pour les besoins de [http://phpcodeur.net/wascripts/wanewsletter/ Wanewsletter], date de 2003. Bref, tout cela méritait un bon nettoyage, et la tentation de tout refaire proprement était forte…

Je préfère vous laisser lire le code plutôt que de tenter de vous décrire de manière obscure et maladroite la façon dont j’ai souhaité architecturer l’ensemble.

Voici un exemple basique d’utilisation:

{{{
#!php
<?php
require 'mailer.class.php';

$email = new Email();
$email->addRecipient("bobe <my@address.tld>");
$email->setSubject("Ici, le sujet");
$email->setTextBody("Ici, le message");

Mailer::send($email);
?>
}}}

Un autre exemple avec cette fois un message en HTML et un fichier joint:

{{{
#!php
<?php
require 'mailer.class.php';

$message = "<p>Ici, le <strong>message en HTML</strong>!</p>

<p>Une image&nbsp;:</p>
<img src='http://example.org/path/to/image.png' alt='my text'>
<p>Ciao!</p>";

$email = new Email();
$email->setFrom('one@example.org', 'Aurélien');
$email->addRecipient('my@address.tld', 'bobe');
$email->setSubject("Ici, le sujet");
$email->setHTMLBody($message);
$email->attach('/path/to/file');

Mailer::send($email);
?>
}}}

Vous pouvez constater que la méthode addRecipient() peut s’utiliser de deux façons différentes (idem pour les méthodes setFrom() et setReplyTo()). Soit en passant une chaîne valide selon la [http://www.ietf.org/rfc/rfc2822.txt RFC2822], soit en passant le nom de personnalisation en deuxième argument. Notez que ce nom doit être encodé d’une certaine manière s’il contient certains caractères ascii réservés, ou des caractères non ascii. Cela est fait automatiquement seulement si le nom est passé en deuxième argument de la méthode addRecipient().

Le même exemple, mais en attachant une image que nous allons utiliser dans le code HTML (image embarquée):

{{{
#!php
<?php
require 'mailer.class.php';

$message = "<p>Ici, le <strong>message en HTML</strong>!</p>

<p>Une image&nbsp;:</p>
<img src='cid:myimage.png' alt='my text'>
<p>Ciao!</p>";

$email = new Email();
$email->setFrom('one@example.org', 'Aurélien');
$email->addRecipient('my@address.tld', 'bobe');
$email->setSubject("Ici, le sujet");
$email->setHTMLBody($message);
$email->attach('/path/to/file.png', 'myimage.png');

Mailer::send($email);
?>
}}}

Comme vous le voyez, il suffit d’utiliser le nom de l’image dans la balise <img/> avec le scheme spécial 'cid' (voir la [http://www.faqs.org/rfcs/rfc2111 RFC 2111]).

Enfin, voici un exemple d’envoi en boucle (utilisation typique d’envoi d’une lettre d’information):

{{{
#!php
<?php
// $addressList contient un tableau d'adresses destinataires

require 'mailer.class.php';

$message = "Ici, le message!";

$email = new Email();
$email->setFrom('one@example.org', 'Aurélien');
$email->setSubject("Ici, le sujet");
$email->setTextBody($message);

foreach( $addressList as $address ) {
    $email->headers->remove('To');
    $email->addRecipient($address);
    Mailer::send($email);
}

?>
}}}

[D’autres exemples ou une page 'exemple' à venir]

== Liste des choses à faire ==

À la date du 10 août 2006, voici la liste des choses restant à faire:

 * Une documentation sommaire comme celle qui existe pour les versions 2.x
 * Décider d’une façon de gérer les erreurs (plutôt à coup de trigger_error() ou en lançant des exceptions ?)
 * Finir de revoir la classe smtp et les parties l’utilisant
 * Au chargement d’un email avec la méthode Email::load(), pouvoir parser complètement l’email ?
 * Peaufiner/tester la classe !SecureMail (OpenPGP)

En dehors de ça, wamailer 3.0 dans son état actuel fonctionne très bien pour envoyer des emails texte, html, multi-format, avec pièces jointes, etc.
L’API est à peu près figée.

== Dépôt Git et Téléchargement ==

Le code source de Wamailer a migré de Subversion vers Git et un dépôt public a été ajouté sur Github.com à cette adresse : https://github.com/wascripts/wamailer
Pour récupérer le code actuel en développement, indiquez la commande suivante :

{{{git clone https://github.com/wascripts/wamailer.git}}}

N’hésitez pas à tester tout cela et à me faire parvenir vos remarques! [[BR]]
 ''Bobe''


== Liens ==

 * [http://phpcodeur.net/wascripts/wamailer/ Wamailer] -- Présentation de Wamailer sur le site phpcodeur.net
 * [https://github.com/wascripts/wamailer] -- Espace de développement de Wamailer 3 sur Github