Helper Email

1Présentation

Helper servant à envoyer des emails, avec la possibilité d'envoyer de simples messages en texte brut, ou des messages plus complexes (format HTML et texte, pièces-jointes).

L'objet \Temma\Utils\Email propose des méthodes statiques permettant d'envoyer rapidement des emails. Il propose aussi un fonctionnement plus classique, en l'appelant via le composant d'injection de dépendances, qui permet notamment de profiter de paramètres configurés dans le fichier etc/temma.php.

Il est fortement recommandé d'utiliser le fonctionnement classique (pas les méthodes statiques), car cela permet de configurer les envois. Par exemple, il vous sera possible de désactiver les envois de mail lorsque vous déployez votre site sur un serveur de test ; ou encore de restreindre les envois à certains domaines.

2Méthodes statiques

2.1simpleMail()

Cette méthode statique permet d'envoyer facilement un email dont le contenu est en texte brut.

Signature de la méthode :

simpleMail(string $from, string|array $to, string $title='',
           string $message='', string|array $cc='',
           string|array $bcc='', ?string $envelopeSender=null) : void

Paramètres :

  • $from : Expéditeur du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $to : Destinataire du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $title : Titre du message.
  • $message : Contenu textuel du message.
  • $cc : Destinataire en copie du message, ou liste de destinataires.
  • $bcc : Destinataire en copie cachée, ou liste de destinataires.
  • $envelopeSender : Adresse de l'expéditeur transmise à sendmail.

Exemple :

use \Temma\Utils\Email as TµEmail;

// envoi d'un message en texte brut
TµEmail::simpleMail('luke@rebellion.org', 'vader@empire.com',
                    "Je n'y crois pas", "Tu es mon père ?");

2.2fullMail()

Cette méthode statique permet d'envoyer des emails en texte brut et/ou en HTML, éventuellement accompagnés de pièces jointes.

Signature de la méthode :

fullMail(string $from, string|array $to, string $title='',
         string $html='', ?string $text=null, ?array $attachments=null,
         string|array $cc='', string|array $bcc='',
         ?string $unsubscribe=null, ?string $envelopeSender=null) : void

Paramètres :

  • $from : Expéditeur du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $to : Destinataire du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $title : Titre du message.
  • $html : Contenu du message au format HTML.
  • $text : Contenu textuel du message.
  • $attachments : Liste de pièces-jointes, chacun représentée par un tableau associatif contenant les clés suivantes :
    • filename : Nom du fichier.
    • mimetype : Type MIME du fichier.
    • data : Contenu binaire du fichier.
  • $cc : Destinataire en copie du message, ou liste de destinataires.
  • $bcc : Destinataire en copie cachée, ou liste de destinataires.
  • $unsubscribe : Contenu de l'en-tête SMTP List-Unsubscribe.
  • $envelopeSender : Adresse de l'expéditeur transmise à sendmail.

Exemple :

use \Temma\Utils\Email as TµEmail;

TµEmail::fullMail('vader@empire.com', "luke@rebellion.org",
                  "Salut gamin", "<h1>Eh oui</h1><p>Je suis ton père</p>");

3Méthodes orientées objet

Ces méthodes nécessitent que l'objet soit instancié via le composant d'injection de dépendances.

Leur comportement peut être contrôlé avec le fichier de configuration, ainsi que par l'utilisation de méthodes de configuration (voir plus bas).

3.1textMail()

Cette méthode permet d'envoyer de simples messages dont le message est en texte brut, sans pièce jointe.

Signature de la méthode :

textMail(string $from, string|array $to, string $title='',
         string $message='', string|array $cc='',
         string|array $bcc='', ?string $envelopeSender=null) : void

Paramètres :

  • $from : Expéditeur du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $to : Destinataire du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $title : Titre du message.
  • $message : Contenu textuel du message.
  • $cc : Destinataire en copie du message, ou liste de destinataires.
  • $bcc : Destinataire en copie cachée, ou liste de destinataires.
  • $envelopeSender : Adresse de l'expéditeur transmise à sendmail.

Exemple :

// envoi d'un message en texte brut
$from = 'luke@rebellion.org';
$to = 'vader@empire.com';
$title = "Je n'y crois pas";
$text = "Tu es mon père ?";
$this->_loader['\Temma\Utils\Email']->textMail($from, $to, $title, $text);

3.2mimeMail()

Cette méthode permet d'envoyer des emails en texte brut et/ou en HTML, éventuellement accompagnés de pièces jointes.

Signature de la méthode :

mimeMail(string $from, string|array $to, string $title='',
         string $html='', ?string $text=null, ?array $attachments=null,
         string|array $cc='', string|array $bcc='',
         ?string $unsubscribe=null, ?string $envelopeSender=null) : void

Paramètres :

  • $from : Expéditeur du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $to : Destinataire du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $title : Titre du message.
  • $html : Contenu du message au format HTML.
  • $text : Contenu textuel du message.
  • $attachments : Liste de pièces-jointes, chacun représentée par un tableau associatif contenant les clés suivantes :
    • filename : Nom du fichier.
    • mimetype : Type MIME du fichier.
    • data : Contenu binaire du fichier.
  • $cc : Destinataire en copie du message, ou liste de destinataires.
  • $bcc : Destinataire en copie cachée, ou liste de destinataires.
  • $unsubscribe : Contenu de l'en-tête SMTP List-Unsubscribe.
  • $envelopeSender : Adresse de l'expéditeur transmise à sendmail.

Exemple :

// expéditeur, destinataire et titre du message
$from = 'vader@empire.com';
$to = 'luke@rebellion.org';
$title = 'Salut gamin';
// message aux formats HTML et texte brut
$html = "<h1>Eh oui</h1><p>Je suis ton père</p>";
$text = "Eh oui. Je suis ton père";
// pièce-jointe
$attachments = [
    [
        'filename' => 'viens_du_cote_obscur.pdf',
        'mimetype' => 'application/pdf',
        'data'     => file_read_contents('formulaire_inscription.pdf'),
    ],
];
// instanciation de l'objet
$email = $this->_loader['\Temma\Utils\Email'];
// envoi du message
$email->mimeMail($from, $to, $title, $html, $text, $attachments);

3.3templatedMail()

Cette méthode permet d'envoyer des emails en texte brut et/ou en HTML, éventuellement accompagnés de pièces jointes. Les message texte et HTML sont générés à partir de templates Smarty et de données qui sont transmises aux templates.

Signature de la méthode :

templatedMail(string $from, string|array $to, string $title='',
              ?string $htmlTplPath=null, ?string $textTplPath=null,
              ?array $templateData=null,?array $attachments=null,
              string|array $cc='', string|array $bcc='',
              ?string $unsubscribe=null, ?string $envelopeSender=null) : void

Paramètres :

  • $from : Expéditeur du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $to : Destinataire du message, de la forme "adresse@domaine" ou "Nom <adresse@domaine>".
  • $title : Titre du message.
  • $htmlTplPath : Chemin vers le template au format HTML.
    Peut être un chemin absolu ou un chemin relatif au répertoire templates/ du projet.
  • $textTplPath : Chemin vers le template au format texte.
    Peut être un chemin absolu ou un chemin relatif au répertoire templates/ du projet.
  • $templateData : Tableau associatif contenant les données à transmettre aux templates.
  • $attachments : Liste de pièces-jointes, chacun représentée par un tableau associatif contenant les clés suivantes :
    • filename : Nom du fichier.
    • mimetype : Type MIME du fichier.
    • data : Contenu binaire du fichier.
  • $cc : Destinataire en copie du message, ou liste de destinataires.
  • $bcc : Destinataire en copie cachée, ou liste de destinataires.
  • $unsubscribe : Contenu de l'en-tête SMTP List-Unsubscribe.
  • $envelopeSender : Adresse de l'expéditeur transmise à sendmail.

Exemple :

// expéditeur, destinataire et titre du message
$from = 'vader@empire.com';
$to = 'luke@rebellion.org';
$title = 'Salut gamin';
// chemins vers les templates aux formats HTML et texte brut
$htmlTpl = 'emails/message_pour_luke/html.tpl';
$textTpl = 'emals/message_pour_luke/text.tpl';
// données de templates
$data = [
    'nom'  => 'Lukounet',
    'arme' => 'sabre laser',
];
// pièce-jointe
$attachments = [
    [
        'filename' => 'viens_du_cote_obscur.pdf',
        'mimetype' => 'application/pdf',
        'data'     => file_read_contents('formulaire_inscription.pdf'),
    ],
];
// instanciation de l'objet
$email = $this->_loader['\Temma\Utils\Email'];
// envoi du message
$email->templatedMail($from, $to, $title, $htmlTpl, $data, $textTpl, $attachments);

3.4Fichier de configuration

Les méthodes textMail(), mimeMail() et templatedMail() sont affectées par les valeurs qui peuvent être configurées dans le fichier etc/temma.php. Cela permet par exemple de forcer la mise en copie de destinataires pour tous les messages envoyés. 

<?php

return [
    'x-email' => [
        'disabled'       => true,
        'allowedDomains' => [ 'temma.net', 'github.com' ],
        'cc'             => 'leia@rebellion.org',
        'bcc'            => [
            'palpatine@empire.com',
            'yoda@jedi.org',
        ],
        'envelopeSender' => 'administrator@blackstar.com',
    ]
];
  • Ligne 5 : En ajoutant le paramètre disabled et en lui donnant la valeur true, vous désactivez complètement l'envoi d'emails.
  • Ligne 6 : Liste de domaines vers lesquels l'envoi de messages est autorisé.
  • Ligne 7 : Destinataire ajouté en copie conforme. Cette variable peut prendre une chaîne de caractères contenant un destinataire (de la forme "adresse@domaine.com" ou "Nom <adresse@domaine.com>", ou une liste de destinataires.
  • Ligne 8 : Destinataires ajoutés en copie cachée. Cette variable peut prendre une chaîne de caractères contenant un destinataire (de la forme "adresse@domaine.com" ou "Nom <adresse@domaine.com>", ou une liste de destinataires.
  • Ligne 12 : Définition de l'adresse envoyée comme "envelope-sender" (aussi appelé "return path") dans les en-têtes SMTP. Cela peut être nécessaire dans le cas de relais SMTP.

3.5Méthodes de configuration

Il est possible d'utiliser des méthodes pour modifier le comportement des méthodes textMail(), mimeMail() et templatedMail(). Ces méthodes écrasent les valeurs éventuellement définies dans le fichier de configuration. 

$email = $this->_loader['\Temma\Utils\Email'];

// désactiver tous les envois
$email->enable(false);
// réactiver
$email->enable(true);

// définition des noms de domaines autorisés
$email->setAllowedDomains(['temma.net', 'github.com']);

// ajout d'un destinataire en copie
$email->setCc('contact@monsupersiteweb.com');
// ajout de plusieurs destinataires en copie
$email->setCc(['aa@bb.com', 'yy@zz.com']);

// ajout d'un destinataire en copie cachée
$email->setBcc('aa@bb.com');
// ajout de plusieurs destinataires en copie cachée
$email->setBcc(['aa@bb.com', 'yy@zz.com']);

// définition de l'en-tête SMTP "envelope-sender"
$email->setEnvelopeSender('administrator@blackstar.com');