Raccourcis : Contenu - rubriques - sous rubriques
EN FR

jMailer est une classe permettant l'envoi d'email depuis un contrôleur ou une classe métier. Elle est basée sur la classe PHPMailer.

Voici ses possibilités :

  • envoi de pièces jointes
  • Email en HTML ou text
  • Destinataires multiples
  • Plusieurs méthodes d'envoi
  • Support de l'authentification SMTP

De nombreux exemples d'utilisation sont disponibles sur internet. Aussi nous n'allons pas détailler la manière dont on utilise cette classe.

jMailer apporte quelques fonctionnalités supplémentaires et une façon particulière de configurer l'envoi de mail :

  • la configuration générale d'envoi de mail est indiqué dans le fichier de configuration de votre application
  • possibilité d'utiliser les templates jTpl pour générer le contenu des mails.
  • messages d'erreurs traduisible via les fichier properties de jLocale.
  • les erreurs sont renvoyées via des exceptions.

Paramétrage de base

Le paramétrage de base utilisé par jMailer s'effectue dans le fichier var/config/localconfig.ini.php de votre application dans la section [mailer].

Les principales options de configuration

  • webmasterEmail : l'email par defaut utilisé pour l'envoi des mails (expéditeur)
  • webmasterName : le nom par défaut utilisé pour l'envoi des mails (expéditeur)
  • mailerType : méthode utilisée pour envoyer les emails (par défaut mail)
    • "mail" : utilise la fonction mail de PHP
    • "sendmail" : utilise directement la fonction mail du serveur
    • "smtp" : utilise une connexion directe à un/plusieurs hôte SMTP
  • hostname : utilisé dans les en-têtes Message-Id et Received, et aussi comme valeur par defaut pour HELO. Si vide, utilisera la valeur renvoyée par $_SERVER['SERVER_NAME'] ou "localhost.localdomai".
  • sendmailPath : pour l'envoi par sendmail, le chemin de l'executable sendmail.

jMailer utilise aussi les paramètres généraux locale et charset pour configurer la langue et l'encodage des mails.

Bien sûr, tout ces paramètres sont modifiables pour des besoins ponctuels en utilisant les méthodes et propriétés adéquates.

Note à propos de webmasterEmail : si vous n'utilisez pas un serveur SMTP directement, assurez-vous que le serveur web est autorisé à envoyer des emails avec cette adresse. Des serveurs SMTP pourraient les refuser ou les considérer comme du spam (voir mettre votre serveur dans une liste noire). Par exemple, si votre serveur est publique, vous devez avoir un enregistrement SPF dans la configuration DNS du domaine utilisé. Cet enregistrement doit contenir entre autre l'IP du serveur web. Il y a aussi la configuration DKIM que vous pouvez mettre en place. Mais ceci est hors contexte.

Configuration SMTP

Si vous choisissez d'envoyer les mails via un serveur SMTP spécifique, vous devez indiquer comment se connecter à ce serveur en créant un profil dans var/config/profiles.ini.php. Le nom du profil doit commencer par smtp: suivi d'un nom de votre choix.

Exemple :


[smtp:mymailer]
host = localhost
; habituellement, 587, 465 ou 25 (non sécurisé)
port = 587 ; ou 465, ou 25

;connection sécurisée ou pas (valeurs possibles: "", "ssl", "tls" ou "unencrypted")
secure_protocol = tls
timeout = 20

; Active ou non l'authentification
auth_enabled = on
username = me@foo
password = thepassword

Quand secure_protocol est vide, PHPMailer essaye d'utiliser TLS pour se connecter. La valeur unencrypted force PHPMailer à ne pas utiliser TLS ou SSL, et se connecte en clair au serveur. Cette valeur ne doit être utilisé que sur des réseaux locaux.

Ensuite vous devez indiquer le nom du profil dans le paramètre smtpProfile de la section [mailer] du fichier localconfig.ini.php :


[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp
smtpProfile = mymailer

Vous pouvez aussi paramétrer l'accès SMTP comme dans Jelix 1.6, bien que cette façon de faire soit obsolète. Il n'y a pas de profil, ni de paramètre smtpProfile. Vous devez indiquer les paramètres suivant dans la section [mailer].


[mailer]
webmasterEmail = webmaster@foo.com
mailerType = smtp

; paramètres obsolètes pour la configuration SMTP
smtpHost = localhost
smtpPort = 465
smtpSecure = ssl
smtpHelo=
smtpTimeout = 20
smtpAuth = on
smtpUsername = "me@foo"
smtpPassword = thepassword

Envoi d'un email basique

Envoi d'un email texte avec le paramétrage par défaut.


  $mail = new jMailer();

  $mail->Subject = 'Sujet de l\'email';
  $mail->Body = 'Contenu du message texte';

  $mail->AddAddress('destinataire@exemple.com' , 'Nom du destinataire');

  $mail->Send();

Envoi d'un email basé sur un fichier jTpl

Vous pouvez utiliser toutes la puissance de jTpl a l'intérieur de vos mail. Pour Cela il vous suffit de créer un fichier .tpl dans l'un de vos module.

Exemple dans modules/monmodule/templates/supermail.tpl :


    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'votre nom<votre@mail.com>'}
    {meta Sender 'votre@mail.com'}
    {meta ReplyTo array('votre nom<votre@mail.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>')}
    {meta bcc array('tutu <tutu@example.com>')}

    Salut {$name},

    Voici un super mail généré par jMailer et Jelix.

Et dans votre code PHP :


    $mail = new jMailer();
    $tpl = $mail->Tpl('monmodule~supermail');
    $tpl->assign('name', 'Monsieur Toto');
    $tpl->assign('email', 'toto@example.com');
    $mail->Send();

Il est à noter que jMailer créé des variables de templates correspondantes à des propriétés (protégées) de PHPMailer. Vous pouvez ainsi y accéder dans votre template.


    {meta Subject 'Super mail.'}
    {meta Priority 1}
    {meta From 'votre nom<votre@mail.com>'}
    {meta Sender 'votre@mail.com'}
    {meta ReplyTo array('votre nom<votre@mail.com>')}
    {meta to array($name.'<'.$email.'>')}
    {meta cc array('titi <titi@example.com>', 'tutu <tutu@example.com>')}

    Salut {$name},

    Voici un super mail généré par jMailer et Jelix. Il est en copie à :
    {foreach $cc as $person}
      - {$person[0]}
    {/foreach}

Envoi d'un email en HTML

Pour envoyer un email en HTML, il suffit d'appeler la méthode isHTML() comme dans l'exemple suivant :


$mail = new jMailer();
$mail->isHTML(true);
$mail->Body = "<p>Envoi d'un mail en <strong>HTML</strong> !</p>";
$mail->AddAddress('toto@example.com' , 'Toto');
$mail->Send();

Vous pouvez aussi utiliser un template en HTML, il faut alors indiquer true à la méthode Tpl en second paramètre.


$tpl = $mail->Tpl('monmodule~supermail', true);

PHPMailer incluera dans le mail le contenu HTML que vous donnez, mais aussi une version purement textuelle de votre contenu, en enlevant les balises HTML, les rêgles css et le code javascript. jMailer améliore la conversion en préservant les liens des balises <a>, c'est à dire en affichant les URLS des liens entre parenthèses après l'intitulé du lien, sauf si il y a un attribut ou une classe notexpandlink.

Vous pouvez fournir votre propre convertisseur HTML vers texte, en l'indiquant en troisième paramètre à Tpl(). Cela doit être un paramètre de type callable.


$tpl = $mail->Tpl(
    'mymodule~supermail',
    true,
    function ($html) {
        // ... convert to text
        return $text;
    }
);

Votre HTML peut avoir des images, avec la balise <img>. Si l'attribut src n'est pas une URL, alors PHPMailer considère que c'est un chemin de fichier sur le disque, et inclus l'image dans le mail. Le chemin de l'image indiqué peut être un chemin absolu sur le disque. Si c'est un chemin relatif, vous devez indiquer en quatrième paramètre de Tpl() le chemin de base des images.

Dans cet exemple, les images affichées dans le mail se trouvent dans le répertoire www/images/ de l'application.


$tpl = $mail->Tpl(
    'mymodule~supermail',
    true,
    null,
    jApp::wwwPath('images/')
);

Envoi d'un email avec pièce jointe

L'envoi de fichier en pièce jointe se fait très simplement, en donnant le chemin du fichier stocké sur le disque, et le nom que l'on veut faire apparaitre.


$mail = new jMailer();
$mail->AddAttachment(jApp::varPath('nom_fichier_original.pdf'), 'nom_fichier_pour_email.pdf');
...
$mail->Send();

Utiliser les fonctionnalités avancées de jMailer

jMailer utilise comme base PHPMailer, si vous voulez avoir d'avantage de documentation, consultez la documentation de PHPMailer.

Tester la configuration

Si vous voulez savoir si jMailer enverra correctement les emails avec la configuration effectuée, vous pouvez lancer la commande php console.php mailer:test. Donnez une adresse email à cette commande, et un email sera envoyé à cette adresse.

` php console.php mailer:test john.doe@example.com `

Mode Debug

Dans certains environnement de tests, comme votre machine de développement, vous ne voudriez pas envoyer de mail. Pour désactiver l'envoi de mail, mettez mailerType = file, et tous les mails seront enregistrés dans des fichiers dans var/mails/. Cela vous permet de vérifier le contenu des mails qui ont été générés.

Sur un serveur de démo où vous voulez quand même envoyer des mails, vous avez des fonctionnalités qui facilitent le débuggage.

Si vous voulez par exemple avoir une copie fichier de tous les emails envoyés, mettez copyToFiles = on dans la section mailer.

À partir de Jelix 1.6.17, vous pouvez forcer les destinataires des mails, ainsi tous les mails iront chez eux plutôt que chez le destinataire indiqué dans le mail.

Pour activer cette fonctionnalité, mettez debugModeEnabled = on, et la liste des destinataires dans debugReceivers. Ici, tous les mails seront envoyés à Bob et à Joe, même si d'autres destinataires sont indiqués dans les mails.


debugModeEnabled = on
debugReceivers[] = bob@foo.local
debugReceivers[] = joe@foo.local

Vous avez d'autre paramètres :


; Préfixe à ajouter au sujet des mails
debugSubjectPrefix = "[DEMO] "

; Phrase précédent la liste des en-têtes originaux insérés dans le corp du mail
debugBodyIntroduction = "This is a mail from test. Here are real headers: "

; Type de destinataires à forcer
; 1: uniquement les adresses indiquées dans debugReceivers
; 2: uniquement l'utilisateur courant si il a un email, ou à debugReceivers si il
;    n'est pas authentifié
; 3: les deux, adresses de debugReceivers et adresse de l'utilisateur courant
debugReceiversType = 3

; Les destinataires suivants à qui sont envoyés les mails (direct ou en copie),
; reçevront leurs emails et ne seront donc pas remplacé par ceux de debugReceivers
debugReceiversWhiteList[] = john@foo.local

Vous pouvez aussi débugger la communication SMTP. Utilisez le paramètre de configuration debugSmtpLevel pour indiquer ce que vous voulez voir dans les logs de l'application :

  • 0: Pas de débuggage
  • 1: Commandes SMTP
  • 2: Données et commandes
  • 3: Données, commandes et état de connection
  • 4: données bas-niveau