LIBMAIL

Description

Cette librairie offre une interface objet pour l'envoi de mail.

Important! utilisateurs de la v1.2., téléchargez la derniere version. la version 1.2. contient un bug empechant l'attachement de fichiers de fonctionner.

Quelques possibilites de libMail sont :

Envoyer un ou plusieurs fichiers attachés
Inclure un ou plusieurs destinataires en CC ( copie carbone )
Envoie a un ou plusieurs destinataires en BCC ( copie carbone invisible)
Formatter un message Mail "ready to send" sans l'envoyer effectivement.
Verifier automatiquement la syntaxe des adresses
Inclure un accusé de réception

ChangeLog

version 1.3

BUG FIX - file attachment didn't work
serious rewrite of the class
small optimization in _build_attachement()

version 1.2

added ReplyTo( $address ) method
added Receipt() method to add a mail receipt
added optional charset parameter to Body() method . should fix charset problem on some mail clients

version 1.1

added optional mimetype and disposition parameters to Attach() method
fixed parenthesis bug in sizeof()

Synopsis

	include "libmail.php";
	$m= new Mail; // create the mail
	$m->From( "leo@isp.com" );
	$m->To( "destination@somewhere.fr" );
	$m->Subject( "the subject of the mail" );
	$m->Body( "Hello\nThis is a test of the Mail component" );	// set the body
	$m->Cc( "someone@somewhere.fr");
	$m->Bcc( "someoneelse@somewhere.fr");
	$m->Priority(4) ;	// set the priority to Low
	$m->Attach( "/home/leo/toto.gif", "image/gif", "inline" ) ;	// attach a file of type image/gif to be displayed in the message if possible
	$m->Send();	// send the mail
	echo "Mail was sent:<br><pre>", $m->Get(), "</pre>";

Installation

Telecharger libmail.zip

Contenu:

libmail.php: le composant Mail
libmail_fr.html: Documentation en français
libmail_en.html: Documentation en anglais

Aucune configuration n'est requise dans la librairie. Pour ce qui est de php, dans php3.ini [ou php.ini pour PHP4] :

configurer l'adresse d'envoi sendmail_from
configurer le serveur de mail SMTP

	SMTP           = smtp@isp.com			; for win32 only
	sendmail_from  = valid_address@chezmoi.fr	;for win32 only

Documentation

Descriptions des methodes publiques ( ie. accessibles ) du composant Mail.

Constructeur

Creation de l'instance de graphique

	$mail = new Mail();

Subject( string sujet )

Defini la ligne de sujet du e-mail. Appel optionnel.

	$mail->Subject( "Bonjour, monde" );

From( address )

Defini l'expediteur du mail. Appel obligatoire.

	$mail->From( "me@isp.com" );

To( mixed address )

Defini le ou les destinataires du mail. Appel obligatoire.

	$mail->To( "you@isp.com" );

	$tos = array( "you@isp.com", "u2@isp.com" );
	$mail->To( $tos );

Cc( mixed address )

Permet de définir un ou plusieurs destinataires en carbon-copy. Le paramètre address peut etre au choix une adresse ou un tableau d'adresses.

	$mail->Cc( "toto@somehost.fr" ); // un seul destinataire en CC

	$multiple_cc = array( "a@isp.com", "b@isp.com", "c@isp.com" );
	$mail->Cc( $multiple_cc ); // plusieurs destinataires en CC

Bcc( mixed address )

Permet de définir un ou plusieurs destinataires en carbon-copy discrète. Pour info: A la difference du CC, les adresses mises en BCC n apparaissent pas dans le mail recu par le destinataire principal. le paramètre address peut etre au choix une adresse ou un tableau d'adresses.

	$mail->BCC( "manager@somehost.fr" );

	$multiple_bcc = array( "a@isp.com", "b@isp.com", "c@isp.com" );
	$mail->BCC( $multiple_bcc ); // plusieurs destinataires

Body( string body, [string charset] )

Permet de definir le corps du message. Le champ optionnel charset permet de définir le jeu de caractères du message. Par défaut le charset utilisé est "us-ascii". Utilisez le charset "iso-8859-1" si votre message comporte des caractères accentués "européens".

	$mail->Body( "Message in english" );
	$mail->Body( "Message avé dé accents", "iso-8859-1" );

Note: n'inserer que du text, pas de HTML. Voir Conseils pour envoyer un mail HTML.

Attach( string filename, [ [string mimetype], string disposition] )

Joint un fichier $filename au Mail

filename : emplacement du fichier sur le disque.
mimetype : chaine definissant le type du fichier.

disposition : code definissant la methode d'affichage du fichier par le client mail. Avec inline (valeur par defaut), le client mail affichera la piece jointe dans le message si possible. Avec attachment, la piece jointe sera affiche sous forme de lien.

	// le fichier se trouve dans le repertoire courant
	$mail->Attach( "logo.gif", "image/gif" );

	// fichier indique en absolu - affiche sous forme de lien par le client mail
	$mail->Attach( "C:\\Mes Documents\\resume.doc", "application/x-msword", "attachment" );

autoCheck( boolean )

Permet activer ou non la verification automatique avant envoi. La verification porte sur la validité syntaxique des diverses adresses To, From, CC et BCC du mail - l'existence réelle de ces adresses n'est pas verifiée. Elle est par defaut activée (voir code source du contructeur).

	$mail->autoCheck( false ); // deactive la verification des addresses
	$mail->autoCheck( true ); // verification activee

Important : Lorque la verification est activee, toute adresse incorrecte affiche un message d'erreur et arrete le script. Vous pouvez changer ce comportement "radical" en modifiant la methode CheckAdresses().

Organization( string $org )

Defini le champ Organisation du mail. Optionnel.

	$mail->Organization( "My company" );

ReplyTo( string address )

Defini une adresse de réponse différente de l'adresse de l'expéditeur

	$mail->ReplyTo( "helpdesk@mycompany.com" );

Priority( integer $priority )

Defini la priorite du mail. $priority doit etre un entier pris entre 1 (la plus haute) et 5 ( priorite basse ) Cette information est generalement exploitee par le client de messagerie, par exemple mise en avant des messages urgents.

L'appel de Priority() est optionnel. Par defaut la priorite est 3 (normale).

	$mail->Priority( 1 ); // urgent
	$mail->Priority( 3 ); // normal
	$mail->Priority( 5 ); // pas urgent du tout

Receipt()

Ajoute un accusé de reception au mail. Cet accusé de reception est renvoyé à l'expéditeur lorque le destinataire ouvre le message. Le destinataire de l'accusé est le champ From par défaut, sauf si ReplyTo est défini.

	$mail->Receipt();

Warning: cette fonctionnalité n'étant pas standardisée elle n'est supportée que par certains clients Mail.

Send()

Envoie le message. Ne pas oublier d'invoquer cette methode !

	$mail->Send();

Get()

	Renvoie le mail entier au format Raw ( entetes + corps du message )
	Permet par exemple de l'afficher, de le sauvegarder dans un fichier ou un SGBD.

	$msg = $mail->Get();

	//affiche le message sur la page
	echo "Your message has been sent:<br><pre>", nl2br( $msg ) , "</pre>";

	// et le log dans une database
	$msg = str_replace( "'", "''", $msg );
	$bdd->exec(  "insert into Mailbox( user, folder, message, senttime ) values ( 'toto', 'Sent', '$msg', $FCT_CURRENT_TIME" );

Conseils

Envoyer un mail au format HTML

Premier point, que les choses soient claires : je le deconseille...

Cela dit, pour envoyer un mail au format HTML, vous devez passez par une piece attachee comme ci-dessous:

	$fichier = "mail.html"; // contenu du mail
	$mail->Body( "Ce mail est formatte en HTML" );
	$mail->Attach( $fichier, "text/html" );

Si votre page HTML contient des images ou liens externes, pensez :

soit a les (ré)écrire en absolu : http://chez.moi.com/mahomepage.html au lieu de /mahomepage.html
soit a definir un BASE HREF dans l entete. Tous les liens relatifs dans la page le seront par rapport a cette URL.

	<head>
		<base href="http://chez.moi.com/">
		<title>Ma homepage</title>
	</head>

Reste le cas ou vos destinataires n'ont pas acces au Web. Vous devez alors inserer vos images dans votre code HTML; par exemple en utilisant les urls data: decrites dans l'url data:.

Statut

Name	libmail
Lang	php3 / php4
Version	1.3
Lastmod	Thu Oct 12 12:12:36 UTC 2000
Author	Leo West