1. Liste des méthodes de la classe
   
   
   • Mailer()
   • use_smtp()
   • use_sendmail()
   • set_root()
   • set_format()
   • validate_email()
   • validate_email_mx()
   • set_from()
   • set_address() ( anciennement set_to() )
   • set_subject()
   • set_message()
   • set_altmessage()
   • use_template()
   • assign_tags()
   • assign_block_tags()
   • attachment()
   • set_reply_to()
   • set_return_path()
   • set_notify()
   • organization()
   • set_priority()
   • additionnal_header() ( anciennement set_header() )
   
   
2. Propriétés de la classe
   
   
   • smtp_mode
   • persistent_connection
   • sendmail_mode
   • sendmai_path
   • sendmail_cmd
   • text_tpl_ext
   • html_tpl_ext
   • hebergeur
   • format
   • charset
   • encoding
   • server_from
   • valid_syntax
   • debug
   • statut
   • msg_error
   • fix_bug_mail
   
   
3. A propos des tags
4. A propos des modèles
5. Fonctionnement de l'envoi sur plusieurs destinataires
6. Exemple: Envoi d'un email simple au format texte
7. Exemple: Envoi d'un email au format html, avec pièces jointes et incorporées

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 :

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 :

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 :

boolean set_root ( string template_path )

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

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

boolean validate_email ( string email )

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

exemple :

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

exemple :

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.

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)

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.

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 :

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

exemple :

void set_subject ( string subject )

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

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)

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)

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 :

void assign_tags ( array tags )

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

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.

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 :

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

boolean set_reply_to ( [ string email_reply ] )

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

boolean set_return_path ( [ string email_return ] )

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

boolean set_notify ( [ string email_notify ] )

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

boolean organization ( string soc )

Nom de l'organisation émettrice

void set_priority ( mixed priority )

La fonction n'est pas case-sensitive

exemple :

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

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)

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

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)

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

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)

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

Commandes supplémentaires à l'appel de sendmail

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

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

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

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

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

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

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

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)

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

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

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

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.

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 :

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)

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.

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.