Documentation WAmailer 2.0

Sommaire

I. Liste des méthodes de la classe

Initialisation de la classe

void Mailer ( [string root] )

Cette méthode accepte 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.

exemple :

$mailer = new Mailer();

Activation de l'option smtp

void use_smtp ( string hostname [,int port [,string user [,string pass [,string server_from]]]] )

Si vous voulez utiliser un serveur smtp spécifique pour vos envois, 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 l'authentification).
int port est le port auquel se connecter, la valeur par défaut, 25, suffira la plupart du temps.

Vous pouvez également mettre les paramètres de connexion directement dans la classe smtp (fichier class.smtp.php), ce qui vous évitera de faire appel à use_smtp() (vous devrez mettre aussi la propriété smtp_mode à true dans la classe mailer

exemple :

$mailer->use_smtp("smtp.wanadoo.fr", 25);

Activation de l'option sendmail

boolean use_sendmail ( [ string sendmail_cmd [,string sendmail_path ]] )

Si vous voulez utiliser sendmail directement, utilisez cette méthode.
Vous pouvez passer des commandes supplémentaires à sendmail avec le premier argument, et vous devez indiquer le chemin d'accés à sendmail en deuxième argument.
Là aussi, vous pouvez effectuer ces réglages directement dans la classe Mailer (et mettre sendmail_mode à true)

exemple :

$mailer->use_sendmail('-t', '/usr/bin/sendmail');

Définir le dossier des modèles

boolean set_root ( string template_path )

Fournit le chemin vers le dossier contenant les modèles d'emails

Définition du format de l'email

void set_format ( mixed format )

Définit le format de l'email
Pour un email au format texte, vous devez fournir en argument : txt, text, texte ou 1
Pour un email au format html, vous devez fournir en argument : htm, html ou 2
Pour un email au format multi-format, vous devez fournir en argument : alt ou 3

Si vous voulez envoyer un email dans un format autre que celui par défaut (défini avec la propriété format dans la classe), vous devez appeller la méthode set_format() avant d'appeller set_message(), set_altmessage() ou use_template()

Validation syntaxique des emails

boolean validate_email ( string email )

Renvoie true si l'email passé en argument est syntaxiquement valide, false sinon

exemple :

$mailer->validate_email('toto@domaine.com');

Cette méthode peut être appellée sans instancier la classe mailer.

exemple :

Mailer::validate_email('toto@domaine.com');

Pour que les emails fournis via les méthodes telles que set_from() ou encore set_address() soient d'abord validées avec validate_email(), mettez la propriété valid_syntax à true dans la classe mailer.

Validation réelle des emails

boolean validate_email_mx ( string email )

Renvoie true si l'email passé en argument existe réellement, false sinon
Ce n'est pas une méthode miracle pour vérifier si une adresse email est réelle.
Cette méthode se base sur le fait que la majorité des serveurs smtp refuse le relaying (accepter la demande d'une entité extérieure à son réseau et pour destinataire une adresse extérieure elle aussi au réseau), mais il y en a quand même qui l'accepte.
La méthode s'assure néanmoins que le domaine de l'email a bien un échangeur d'email (Mail eXchanger).
(Fonctionne aussi sous windows)

Définition de l'adresse expéditrice

boolean set_from ( string email [, string name] )

string from correspond à l'adresse email de l'envoyeur.
Vous pouvez également spécifier string 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 des destinataires

boolean set_address ( mixed email [, string type ] )

Anciennement set_to() (qui marche toujours, renvoie simplement les données à set_address())

Cette méthode accepte en premier argument une chaîne de caractères représentant une adresse email, ou bien un tableau contenant les adresses email de tous les destinataires.
Vous pouvez indiquer comme deuxieme argument Cc (carbon copy) ou Bcc (blind carbon copy) selon ce que vous désirez.

exemple :

$mailer->set_address("jojo@domaine.com");

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

Vous pouvez personnaliser la aussi le nom du destinataires en utilisant son pseudo (ou autre) comme index du tableau fourni.

exemple :

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

Définition du sujet de l'email

void set_subject ( string subject )

Définit tout simplement le sujet de l'email à envoyer.

Définition du message proprement dit

void set_message ( string message [, array tags ] )

Le corps de l'email.
Vous pouvez passer en deuxième argument un tableau contenant les tags à remplacer dans le texte. (voir section III de la présente documentation)

Définition du message alternatif

void set_altmessage ( string altmessage [, array tags ] )

Le message alternatif pour les logiciels de courriel ne supportant pas le format html (si vous envoyez un mail multi-format)
Vous pouvez passer en deuxième argument un tableau contenant les tags à remplacer dans le texte. (voir section III de la présente documentation)

Définition du modèle à utiliser

boolean use_template ( string template_name [, array tags ] )

Vous devez passer en premier argument le nom du modèle à utiliser (nom du fichier 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é. (vous pouvez toutefois changer ces extensions, regardez du coté des propriétés text_tpl_ext et html_tpl_ext)

Vous pouvez passer en deuxième argument un tableau contenant les tags à remplacer dans le texte. (voir section III de la présente documentation)

exemple :

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

Assignation de tags

void assign_tags ( array tags )

A appeller si vous souhaitez ajouter des tags à remplacer (voir section III de la présente documentation).

Assignation de blocks de tags

void assign_block_tags ( string blockname [, array tags ] )

A appeller si vous souhaitez ajouter des blocks de tags à remplacer.
Vous pouvez passer en deuxième argument un tableau contenant les tags spécifiques à ce block que vous souhaitez remplacer (voir section III de la présente documentation).
La classe ne supporte pas actuellement les blocks imbriqués non plus que les blocks répétés. A n'utiliser que pour des blocks conditionnels donc.

Attachement de fichiers joints ou incorporés

boolean attachment ( string path [, string filename [, string disposition [, string mime-type [, boolean embedded ]]]] )

string path : le chemin vers le fichier
string filename : nom du fichier (si omis, le nom du fichier dans path sera utilisé)
string disposition : inline ou attachment
string mime-type : mime_type du fichier
boolean 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', 'new_name.gif', '', 'image/gif', true);

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

Définition de l'adresse de réponse

boolean set_reply_to ( [ string email_reply ] )

Si l'argument est omis, l'adresse définie en from sera utilisée.

Définition de l'adresse de retour d'erreurs

boolean set_return_path ( [ string email_return ] )

Si l'argument est omis, l'adresse définie en from sera utilisée.

Définition de l'adresse de notification de lecture

boolean set_notify ( [ string email_notify ] )

Si l'argument est omis, l'adresse définie en from sera utilisée.

Définition de l'adresse de notification de lecture

boolean organization ( string soc )

Nom de l'organisation émettrice

Définition de la priorité de l'email

void set_priority ( mixed priority )

La fonction n'est pas case-sensitive

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);

Ajout d'entêtes supplémentaires

boolean additionnal_header ( string name, string body )

Anciennement set_header()
Renvoie false si le nom ou le corps de l'entête contiennent des caractères interdits.

Le nom de l'entête ne doit contenir que des caractères us-ascii et ne doit pas contenir le caractère deux points (:)
Le contenu de l'entête ne doit contenir aucun retour chariot ou saut de ligne

Envoi de l'email

boolean send ( [ boolean do_not_send ] )

Renvoie true si l'email a pu être envoyé, false sinon

Vous pouvez passer true en argument pour afficher l'email au lieu de l'envoyer (débogguage)

Top

II. Propriétés de la classe

Certaines propriétés de la classe méritent qu'on s'y attarde.

smtp_mode

Si placée à TRUE, le mode smtp sera utilisé, vous n'aurez donc pas besoin de faire appel à la méthode use_smtp() (pensez cependant à mettre les paramètres d'accés au serveur smtp dans la classe smtp)

persistent_connection

Si placée à TRUE, la connexion au serveur smtp ne sera pas fermée après le premier envoi et sera réutilisée pour un envoi ultérieur. Dans ce cas, ce sera à vous de fermer la connexion au serveur smtp, car le serveur smtp n'effectue les tâches demandées qu'après la fermeture proprement de la connexion.
Pour fermer la connexion au serveur smtp, vous pouvez faire : $mailer->smtp->quit();

sendmail_mode

Si placée à TRUE, le mode sendmail sera utilisé, vous n'aurez donc pas besoin de faire appel à la méthode use_sendmail() (pensez alors à placer le chemin d'accés vers sendmail dans la propriété sendmail_path)

sendmail_path

Mettez y le chemin d'accés vers sendmail si vous utilisez directement l'option sendmail

sendmail_cmd

Commandes supplémentaires à l'appel de sendmail

text_tpl_ext

Extension par défaut des modèles au format texte

html_tpl_ext

Extension par défaut des modèles au format html

hebergeur

Laissez comme c'est, sauf si vous êtes chez Online

format

Le format par défaut des emails envoyés lorsque vous ne faites pas appel à la méthode set_format()

charset

Le jeu de caractère à déclarer dans l'email, changez le si nécessaire

encoding

Encodage par défaut des emails. L'encodage quoted-printable se veut plus léger, mais n'est pas conseillé pour poster sur les newsgroups (vous avez déja dù voir des sujets du type =?iso-8859-1?Q? .. etc ..)

encoding

Nom du serveur émetteur (utilisé pour l'envoi via smtp)

valid_syntax

Placé à FALSE par défaut. Placez cette propriété à true si vous souhaitez que les emails fournis à la classe (via set_from(), set_address(), etc..) soient vérifiés (vérification syntaxique)

debug

Placé à FALSE par défaut. Pour débogguer la classe

statut

Placé à TRUE par défaut. Ne modifiez pas cette propriété ! (les emails ne seraient tout simplement pas envoyés)

msg_error

Contient le message d'erreur renvoyé par la classe si une erreur se produit.

fix_bug_mail

Je ne donnerai pas ici de détails poussés, lisez les commentaires dans la méthode recipients_list() pour en savoir plus.

Vous pouvez vérifier avec un phpinfo si php utilise sendmail (en regardant si sendmail_path contient un chemin vers sendmail).
Si php utilise sendmail, mettez cette propriété à 1, sinon, mettez la à -1
Si cette propriété est laissée à NULL, le script cherchera la réponse par lui même.

Top

III. 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

IV. 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 (vous pouvez toutefois changer ces extensions, regardez du coté des propriétés text_tpl_ext et html_tpl_ext)

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

V. 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

VI. Exemple: Envoi d'un email simple au format texte

Voici un exemple d'envoi d'email.
Ici, nous envoyons un email au format texte (le format par défaut), il y a un destinataire principal, et nous ajoutons un destinataire en copie cachée.

<?php

include('./class.mailer.php');

$mailer = new Mailer();

$mailer->set_from('toto@domaine.com', 'toto');
$mailer->set_address('blob@domaine.net');
$mailer->set_address(array(
    
'fred' => 'fred@domaine.org'
), 'bcc');

$mailer->set_subject('Hello world !');
$mailer->set_message('Je voulais juste faire un petit coucou,

A bientôt :)'
);

if( !
$mailer->send() )
{
    echo
"l'email n'a pu être envoyé";
}

?>

Top

VII. Exemple: Envoi d'un email au format html, avec pièces jointes et incorporées

Ici, on envoie un email au format html à blob@domaine.net.
On a également ajouter un fichier zip en fichier attaché, ainsi qu'une image gif que nous utilisons au sein de l'email html.

<?php

include('./class.mailer.php');

$subject = 'Hello world !';

$message  = '<html><body>';
$message .= 'salut <b>tout le monde</b>, <br /><br />';
$message .= 'Je voulais juste faire un petit %TAG1%<br /><br />';
$message .= 'Voila une image : <br/><img src="cid:picture.gif" border="0" />';
$message .= '<br /><br />A bientôt :)</body></html>';

$mailer = new Mailer();

$mailer->set_from('toto@domaine.com', 'toto');
$mailer->set_address('blob@domaine.net');

$mailer->set_format('html');
$mailer->set_subject($subject);
$mailer->set_message($message, array(
    
'TAG1' => 'coucou'
));

$mailer->attachment('./rep/fichier.zip', 'compressed_file.zip', 'attachment', 'application/x-zip-compressed');
$mailer->attachment('./rep_images/image1.gif', 'picture.gif', '', 'image/gif', true);

if( !
$mailer->send() )
{
    echo
"l'email n'a pu être envoyé";
}

?>

Top