Documentation WAmailer 2.0


Sommaire
  1. Liste des méthodes de la classe
  2. A propos des tags
  3. A propos des modèles
  4. Fonctionnement de l'envoi sur plusieurs destinataires

I. Liste des méthodes de la classe
* Initialisation de la classe : void Mailer ( [string root] )

exemple :
$mailer = new Mailer();

Mailer() prend un argument facultatif.
Si vous utilisez un modèle d'email et que celui ci ne se trouve pas dans le dossier par défaut (défini dans le fichier mailer.php), vous pouvez indiquer le chemin vers le dossier contenant les modèles.

* configuration des paramètres smtp : void set_smtp ( string hostname [,int port [,string user [,string pass]]] )

exemple :
$mailer->set_smtp("smtp.wanadoo.fr", 25);

Si vous voulez utiliser un serveur smtp spécifique, vous devez indiquer dans ce cas les paramètres de connexions au serveur smtp de votre choix, string user et string pass pour l'authentification. (si le serveur smtp supporte la commande AUTH LOGIN)
Seul string hostname est obligatoire.
int port est le port auquel se connecter, la valeur par défaut, 25, suffira la plupart du temps.

Vous pouvez également faire tous ces réglages dans le fichier directement, ce qui vous évitera de faire appel à chaque fois à la fonction set_smtp().

* définition de l'expéditeur : void set_from ( string from [, string from_name] )

exemple :
$mailer->set_from("toto@titi.fr", "toto");

set_from() accepte deux arguments :

string from correspond à l'adresse email de l'envoyeur.
Vous pouvez également spécifier string from_name pour personnaliser le nom de l'expéditeur, dans ce cas, c'est lui qui apparaitra dans le client mail du destinataire.

* définition du destinataire : void set_to ( string/array to [, string type] )

Vous pouvez ajouter un email simplement, ou plusieurs emails dans un tableau.

exemple :
$mailer->set_to("jojo@domaine.com");

// ou encore

$mailer->set_to(array(
    
"jojo@domaine.com",
    
"copain@azerty.net"
));

Vous pouvez personnaliser le nom des destinataires avec l'index du tableau (semble ne pas fonctionner sous windows :/ )

exemple :
$mailer->set_to(array(
    
"jojo@domaine.com",
    
'fred' => "copain@azerty.net"
));

Vous pouvez indiquer comme deuxieme argument cc (carbon copy) ou bcc (blind carbon copy) selon ce que vous désirez.

* le sujet de l'email : void set_subject ( string subject )

exemple :
$mailer->set_subject("exemple de sujet");

* le message proprement dit : void set_message ( string message [, array tags] )

exemple :
$mailer->set_message("voici le message que je vous envoie, simple n'est ce pas ?");

Notez que le deuxième argument est facultatif.


Les méthodes faculatives

* format du message : void set_format ( integer/string format )

1, txt, text, ou texte pour format texte brut
2, htm ou html pour format html
3 ou alt pour email multi format

exemple :
$mailer->set_format(2);

Dans le cas où vous utilisez cette méthode (si vous voulez envoyer un email dans un format autre que celui par défaut), vous devez l'appeller avant set_message() (use_template() si vous utilisez un modèle) !

* réglage du chemin vers les modèles : void set_root ( string template_path )

A utiliser si vous souhaitez modifier le chemin de stockage des modèles (après un précédent envoi par exemple)

exemple :
$mailer->set_root("rep/rep2/");

* Définition de l'email au format texte si envoi d'un email multi-format : void set_altmessage ( string message [, array tags] )

Même fonctionnement que set_message().
A utiliser si vous envoyez un email multi format, pour définir la partie texte brute de l'email

* Définir le nom d'un modèle à utiliser : void use_template ( string file [, array tags] )

Prend en premier argument le nom du modèle (nom du fichier mais sans l'extension)
Si vous envoyez un email au format texte, le fichier doit avoir l'extension .txt, si c'est au format html, le fichier doit avoir l'extension .html, enfin, si vous envoyez un email multi format, les deux fichiers doivent être présent dans le dossier spécifié.
La aussi, l'argument array tags est facultatif pour le cas où vous n'avez pas de tags à remplacer.

exemple :
$mailer->use_template("new_mail", array(
    
'PSEUDO' => 'testeur',
    
'TEST' => 'ceci est un test'
));

* Définir le nom d'un modèle à utiliser : void assign_tags ( array tags )

Si vous avez des tags à ajouter.

* Définit un block du modèle à afficher : void assign_block_tags ( string block_name [, array tags] )

Si vous avez mis un block dans votre modèle et que vous souhaitez l'afficher.
Utilisez le deuxième argument pour spécifier des tags spécifiques au block, à remplacer
La classe ne supporte pas les blocks imbriqués non plus que les blocks répétés. A n'utiliser que pour des blocks conditionnels donc .

* attacher des fichiers à l'email (pièces jointes) : void attachment ( string path [, string filename [, string disposition [, string mime-type [, boolean embedded]]]] )

path : le chemin vers le fichier
filename : nom du fichier (si omis, le nom du fichier dans path sera utilisé)
disposition : inline ou attachment
mime-type : mime_type du fichier
embedded : true si le fichier doit être intégré dans le corps du message (seulement si email html)
Si le fichier est incorporé dans le message html (embedded) vous devez utiliser cid:nom_du_fichier en lieu et place du contenu de l'attribut src de la balise html.

exemple :
$mailer->attachment('../rep/image.gif', 'image.gif', '', 'image/gif', true);

et dans le corps du message : <img src="cid:image.gif" border="0" /> là où vous le souhaitez

* Définir l'adresse de réponse : void set_reply_to ( [ string email_reply ] )

Si l'argument est omis, l'adresse définie en from sera utilisée (mais dans ce cas, c'est inutile car par défaut c'est celle utilisée lors de l'appel de set_from())

* Définir l'adresse de retour d'erreur : void set_return_path ( [ string email_return ] )

Si l'argument est omis, l'adresse définie en from sera utilisée (mais dans ce cas, c'est inutile car par défaut c'est celle utilisée lors de l'appel de set_from())

* Définir l'adresse de notification : void set_notify ( [ string email_notify ] )

Si l'argument est omis, l'adresse définie en from sera utilisée (mais dans ce cas, c'est inutile car par défaut c'est celle utilisée lors de l'appel de set_from())

* Définir l'organisation : void set_reply_to ( [ string email_reply ] )

Si l'argument est omis, l'adresse définie en from sera utilisée (mais dans ce cas, c'est inutile car par défaut c'est celle utilisée lors de l'appel de set_from())

* définir la priorité de l'email : void set_priority ( integer/string priority )

exemple :

// pour une priorité très haute :
$mailer->set_priority("highest"); ou bien $mailer->set_priority(1);

// pour une priorité haute :
$mailer->set_priority("high"); ou bien $mailer->set_priority(2);      

// pour une priorité normale (priorité par défaut si vous n'utilisez pas cette fonction) :
$mailer->set_priority("normal"); ou bien $mailer->set_priority(3);

// pour une priorité basse :
$mailer->set_priority("low"); ou bien $mailer->set_priority(4);

// pour une priorité très basse :
$mailer->set_priority("lowest"); ou bien $mailer->set_priority(5);

La fonction n'est pas case sensitive

* Definir un entête supplémentaires : void set_header ( string header name, string header value)

Si vous voulez définir des entêtes supplémentaires

Enfin, pour envoyer l'email :
$mailer->send();
Top

II. A propos des tags
Les tags sont des zones de texte spécifiques, définies par %nom_du_tag%, qui vous permettent de les remplacer par un contenu de votre choix.
Par exemple, si vous avez un modèle générique que vous voulez utiliser pour plusieurs personnes différentes et personnaliser, l'email pourrait commencer par Bonjour %PSEUDO%, et vous remplaceriez %PSEUDO% par le contenu approprié à cette personne (en l'occurence le pseudo, issu d'une base de données ou autre ..)

Cela s'applique aussi dans une boucle d'envoi (et c'est évidemment là que c'est le plus utile)

Vous pouvez également définir un block conditionnel. C'est à dire un block dont vous voulez l'affichage dans certaines conditions.
Vous utiliserez donc assign_block_tags() uniquement si les conditions sont remplies, dans ce cas, le texte inclu dans le block sera visible dans l'email
Un block se constitue de la manière suivante :

<!-- start_block nom_du_block -->
texte à afficher si le %nom_du_block.VAR% a été déclaré avec la méthode assign_block_tags()
<!-- end_block nom_du_block -->

Les déclarations de début de block et de fin de block (les commentaires html) doivent être seuls sur leur ligne; vous pouvez là aussi utiliser les tags mais vous remarquerez que les tags du block sont préfixés avec le nom du block suivi d'un point (ceci afin d'éviter des conflits avec des tags de même nom non inclus dans un block)

Voir le fonctionnement des méthodes assign_tags() et assign_block_tags()

La classe ne supporte pas les blocks imbriqués, et les blocks répétés (les dernières données écraseraient les autres)
Top

III. A propos des modèles
Vous pouvez, en ayant réglé le chemin vers le dossier contenant les modèles (à l'initialisation de la classe, ou avec avec la méthode set_root()), utiliser des modèles d'emails.
Les modèles d'emails au format texte doivent avoir l'extension .txt, et ceux pour les emails au format html doivent avoir l'extension .html

Si vous envoyez un email en format multiple, le modèle doit être présent au format texte et html, sans cela, c'est un email au format html qui sera envoyé (sauf si le modèle au format html n'est pas présent)
Top

IV. Fonctionnement de l'envoi sur plusieurs destinataires
Si vous faites plusieurs envois successifs, sachez que la classe garde toutes les données que vous lui avez fournies, aussi, si vous effectuez un second envoi, vous n'avez plus qu'à lui fournir les données qui changent par rapport à l'envoi précédent (ex: envois à plusieurs destinataires, et seul l'email de destination change, inutile de refournir au script le sujet de l'email, le texte, les éventuels fichiers joints, l'email expéditeur ..etc..)

Pour remettre à zéro les variables contenant les données que vous voulez changer, vous avez à votre disposition plusieurs méthodes dont le nom est de type clear_*()
ainsi : clear_to(), clear_from(), clear_subject(), clear_message(), clear_attach() et clear_all()

Leur nom devrait vous donner une bonne indication des données qu'ils réinitialisent ;)

clear_all() est équivalent à la méthode init() de la version 1.x
Top


Powered by phpCodeur © 2002-2003 | WAmailer 2.0
Ce script est distribué librement sous licence GPL