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 deux familles de méthodes.

Les méthodes statiques (simpleMail(), fullMail()) permettent d'envoyer rapidement un email. Elles s'appuient sur la fonction mail() native de PHP : elles nécessitent donc un serveur SMTP local (MTA comme sendmail, Postfix ou Exim) installé et configuré sur la machine.

Les méthodes orientées objet (textMail(), mimeMail(), templatedMail()) s'utilisent via le composant d'injection de dépendances et profitent des paramètres configurés dans le fichier etc/temma.php : choix d'un relais SMTP, désactivation des envois, filtrage des domaines autorisés, ajout de destinataires en copie, etc. Si le transport n'est pas configuré, elles utilisent elles aussi la fonction mail().

Il est fortement recommandé d'utiliser les méthodes orientées objet (plutôt que 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

Ces méthodes envoient les messages via la fonction mail() native de PHP : elles nécessitent donc un serveur SMTP local (sendmail, Postfix, Exim…) installé et configuré sur la machine. N'ayant pas d'état d'instance, elles ne tiennent compte ni de la configuration x-email ni d'un relais ; pour cela, utilisez les méthodes orientées objet.

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.

Contrairement aux méthodes statiques, leur comportement peut être réglé finement : choix d'un relais SMTP (au lieu de la fonction mail() locale), désactivation des envois, filtrage des domaines autorisés, ajout de destinataires en copie, etc. Cela se règle via le fichier de configuration et les 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 = 'emails/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, $textTpl, $data, $attachments);
Échappement HTML. Le template HTML est traité avec l'auto-échappement, selon le réglage de la section de configuration x-smarty (clé autoEscape, activé par défaut). Le template texte, lui, n'est jamais auto-échappé (des entités HTML dans un corps de message texte seraient une erreur).

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', 'temma.org' ],
        '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 utilisée comme "envelope-sender" (aussi appelé "return path") dans l'enveloppe SMTP (commande MAIL FROM). 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'expéditeur d'enveloppe SMTP ("envelope-sender", commande MAIL FROM)
$email->setEnvelopeSender('administrator@blackstar.com');

// définition du transport d'envoi (voir « Envoi via un relais SMTP »)
$email->setTransport($this->_loader->dataSources['mail']);
$email->setTransport('smtp+tls://user:pass@smtp.example.com:587');

4Envoi via un relais SMTP

4.1Principe

Par défaut, le helper Email envoie les messages via la fonction PHP mail(), c'est-à-dire via le serveur de mail local (sendmail/Postfix/Exim). Ce comportement reste inchangé : si vous ne configurez aucun transport, rien ne change pour les applications existantes.

Vous pouvez à la place configurer un transport, qui prend en charge la remise des messages. Le transport peut être n'importe quelle source de données supportant la méthode set() : la source de données SMTP livre le message via un relais ; une source File ou S3 l'archive ; une source de file de messages (SQS, Beanstalk, Redis) le met en attente ; une source Dummy le jette (utile en environnement de test).

Seules les méthodes orientées objet (textMail(), mimeMail(), templatedMail()) peuvent utiliser un transport. Les méthodes statiques simpleMail() et fullMail() n'ont pas d'état d'instance : elles passent toujours par mail().

4.2Configurer le transport

Il existe deux façons de désigner le transport, par ordre de priorité :

  1. Par méthode, à l'exécution (prioritaire sur la configuration) : la méthode setTransport() accepte une source de données déjà instanciée, un DSN (quel que soit le schéma), ou un tableau de paramètres SMTP. 
    $email = $this->_loader['\Temma\Utils\Email'];

// source de données existante (déclarée dans la section "datasources")
$email->setTransport($this->_loader->dataSources['mail']);

// transport à la volée sous forme de DSN
$email->setTransport('smtp+tls://user:pass@smtp.example.com:587');

// ou en paramètres SMTP séparés
$email->setTransport(['host' => 'smtp.example.com', 'port' => 587, 'security' => 'starttls',
                     'user' => 'user@example.com', 'password' => 'p@ss:w/rd!']);
  2. Par configuration : directive transport de la section x-email. Elle accepte trois formes : le nom d'une source de données déclarée dans la section datasources, un DSN (quel que soit le schéma), ou un tableau de paramètres SMTP. Temma fabrique alors la source de données en sous-main. 
    // nom d'une source de données déclarée dans la section "datasources"
'datasources' => [
    'mail' => 'smtp+tls://user:pass@smtp.gmail.com:587',
],
'x-email' => [
    'transport' => 'mail',
],

// ou directement un DSN
'x-email' => [
    'transport' => 'smtp+tls://user:pass@smtp.gmail.com:587',
],

// ou en paramètres SMTP séparés (pratique si le mot de passe contient des caractères spéciaux)
'x-email' => [
    'transport' => [
        'host'     => 'localhost',
        'port'     => 25,
        'security' => 'none',
    ],
],

Une chaîne contenant « :// » est interprétée comme un DSN ; toute autre chaîne est traitée comme le nom d'une source de données déclarée.

En résumé : méthode à l'exécution > configuration. Si rien n'est configuré, le helper utilise mail().

4.3Ce qui est transmis

Quand un transport est configuré, les méthodes orientées objet construisent le message puis effectuent un unique appel set() sur le transport, avec une structure décrivant l'enveloppe et le message :

  • from : expéditeur d'enveloppe (la valeur d'envelopeSender si elle est définie, sinon l'adresse du From), utilisé pour MAIL FROM ;
  • recipients : union dédoublonnée des destinataires to + cc + bcc, utilisée pour les RCPT TO ;
  • message : le message RFC 5322 complet (avec Date et Message-ID), sans en-tête Bcc (les destinataires en copie cachée sont dans l'enveloppe, pas dans le message).

C'est ce qui rend le transport portable : l'enveloppe voyage dans la valeur passée à set(), jamais dans la clé ni dans les options. Une source de données de stockage archive donc le message sans rien perdre. Voir la page de la source de données SMTP pour le détail.

4.4Portabilité et cas particuliers

Le transport est typé \Temma\Base\Datasource (pas spécifiquement SMTP), car le helper n'appelle que la méthode générique set(). Une source de données qui ne supporte pas set() (par exemple les sources AI/OpenAI) lèverait une exception \Temma\Exceptions\Database ; ce cas est marginal et n'est pas géré spécifiquement.

Aspects opérationnels (hors code). La délivrabilité repose surtout sur la configuration DNS et le choix du relais :
  • SPF / DMARC : enregistrements DNS + relais autorisé. Le seul levier applicatif est le contrôle de l'expéditeur d'enveloppe (envelopeSender) et du From, déjà disponibles.
  • DKIM : la signature est généralement assurée par le relais.