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

3.1textMail()

Cette méthode nécessite que l'objet soit instancié via le composant d'injection de dépendances. Elle permet d'envoyer de simples messages dont le message est en texte brut.

Cette méthode utilise les paramètres éventuellement définis dans la configuration (voir plus bas).

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 nécessite que l'objet soit instancié via le composant d'injection de dépendances. Elle permet d'envoyer des emails en texte brut et/ou en HTML, éventuellement accompagnés de pièces jointes.

Cette méthode utilise les paramètres éventuellement définis dans la configuration (voir plus bas).

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.3Configuration

Les méthodes textMail() et mimeMail() 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. 

[
    '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 3 : En ajoutant le paramètre disabled et en lui donnant la valeur true, vous désactivez complètement l'envoi d'emails.
  • Ligne 4 : Liste de domaines vers lesquels l'envoi de messages est autorisé.
  • Ligne 5 : 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 6 : 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 10 : 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.