Les méthodes de la classe

Voici ci-dessous la liste des méthodes de la classe, avec pour chacune, leur définition et utilité.

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

is_online_host()

void is_online_host ()

Cette méthode renvoie true si l’hébergeur est Online, false dans le cas contraire.

use_smtp() : Activation de l’option smtp

void use_smtp ( string server [,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);  

use_sendmail() : 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');  

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

set_format() : 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().

validate_email() : 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@example.org');  

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

Mailer::validate_email('toto@example.org');

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.

validate_email_mx() : Validation réelle des emails

boolean validate_email_mx ( string email, string &errstr )

Renvoie false si l’email passé en argument n'existe pas réellement, true sinon.
Il est important de noter que cette méthode ne renverra false que si le serveur SMTP correspondant renvoie une erreur pour cette adresse. Certains serveurs peuvent très bien répondre par un "250 ok" à n’importe quelle adresse, les erreurs étant traitées ultérieurement au niveau du serveur POP.

Si la méthode renvoie false, l’éventuel message d’erreur retourné par le serveur SMTP sera placé dans la variable errstr passée par référence.

Cette méthode fonctionne également sous Windows mais nécessite alors l’utilisation de la fonction PHP exec().

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

set_from() : 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.

set_address() : 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@example.org');

$mailer->set_address(array(
    'jojo@example.org',
    'copain@example.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@example.org',
    'fred' => 'copain@example.net'
));  

Les chaînes destinataire telles que définies dans la RFC 2822 sont aussi acceptées :

$mailer->set_address('nom <address@example.org>');  

set_subject() : Définition du sujet de l’email

void set_subject ( string subject )

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

set_message() : 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 la section concernant les tags de la présente documentation)

set_altmessage() : 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 la section concernant les tags de la présente documentation)

use_template() : 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 la section concernant les tags de la présente documentation)
Exemple :

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

assign_tags() : Assignation de tags

void assign_tags ( array tags )

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

assign_block_tags() : Assignation de blocks de tags

void assign_block_tags ( string blockname [, array tags ] )

À 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 la section concernant les tags de la présente documentation).
La classe ne supporte pas actuellement les blocks imbriqués non plus que les blocks répétés. À n'utiliser que pour des blocks conditionnels donc.

attachment() : 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.

set_reply_to() : Définition de l’adresse de réponse

boolean set_reply_to ( [ string email ] )

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

set_return_path() : Définition de l’adresse de retour d'erreurs

boolean set_return_path ( [ string email ] )

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

set_notify() : Définition de l’adresse de notification de lecture

boolean set_notify ( [ string email ] )

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

organization() : Définition du nom de l’organisation

boolean organization ( string soc )

Nom de l’organisation.

set_priority() : Définition de la priorité de l’email

void set_priority ( mixed priority )

La fonction n’est pas case-sensitive
Liste des possibilités :

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

additionnal_header() : 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.

send() : 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éboguage).