Email helper

1Presentation

Helper for sending emails, with the option of sending simple plain text messages, or more complex messages (HTML and text format, attachments).

The \Temma\Utils\Email object provides static methods for sending e-mails quickly. It also offers a more traditional way of working, by calling it via the dependency injection component, which allows you to take advantage of parameters configured in the etc/temma.php file.

It is strongly recommended to use the classic operation (not the static methods), as this allows you to configure mailings. For example, you can disable mailings when you deploy your site on a test server; or restrict mailings to some domains.

2Static methods

2.1simpleMail()

This static method makes it easy to send an email with plain text content.

Method signature:

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

Parameters:

  • $from: Sender of the message, in the form "address@domain" or "Name <address@domain>".
  • $to: Recipient of the message, in the form "address@domain" or "Nom <address@domain>".
  • $title: Title of the message.
  • $message: Textual content of the message.
  • $cc: Recipient copied to the message, or list of recipients.
  • $bcc: Recipient in hidden copy, or list of recipients.
  • $envelopeSender: Sender address sent to sendmail.

Example:

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

// send a plain text message
TµEmail::simpleMail('luke@rebellion.org', 'vader@empire.com',
                    "I can't beleive it", "You are my father?");

2.2fullMail()

This static method can be used to send plain text and/or HTML e-mails, with attachments if required.

Method signature:

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

Parameters:

  • $from: Sender of the message, in the form "address@domain" or "Name <address@domain>".
  • $to: Recipient of the message, in the form "address@domain" or "Nom <address@domain>".
  • $title: Title of the message.
  • $html: Message content in HTML format.
  • $text: Textual content of the message.
  • $attachments: List of attachments, each represented by an associative array containing the following keys:
    • filename: File name.
    • mimetype: MIME type of the file.
    • data: Binary content of the file.
  • $cc: Recipient copied to the message, or list of recipients.
  • $bcc: Recipient in hidden copy, or list of recipients.
  • $unsubscribe: Contents of SMTP List-Unsubscribe header.
  • $envelopeSender: Sender address sent to sendmail.

Example:

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

TµEmail::fullMail('vader@empire.com', "luke@rebellion.org",
                  "Hi kid", "<h1>Yep</h1><p>I'm your father</p>");

3Object-oriented methods

These methods require the object to be instantiated via the dependency injection component.

Their behavior can be controlled with the configuration file, as well as by using configuration methods (see below).

3.1textMail()

This method can be used to send simple plain-text messages.

Method signature:

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

Parameters:

  • $from: Sender of the message, in the form "address@domain" or "Name <address@domain>".
  • $to: Recipient of the message, in the form "address@domain" or "Nom <address@domain>".
  • $title: Title of the message.
  • $message: Textual content of the message.
  • $cc: Recipient copied to the message, or list of recipients.
  • $bcc: Recipient in hidden copy, or list of recipients.
  • $envelopeSender: Sender address sent to sendmail.

Example:

// send a plain text message
$from = 'luke@rebellion.org';
$to = 'vader@empire.com';
$title = "I can't beleive it";
$text = "You are my father?";
$this->_loader['\Temma\Utils\Email']->textMail($from, $to, $title, $text);

3.2mimeMail()

This method can be used to send plain text and/or HTML e-mails, with attachments if required.

Method signature:

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

Parameters:

  • $from: Sender of the message, in the form "address@domain" or "Name <address@domain>".
  • $to: Recipient of the message, in the form "address@domain" or "Nom <address@domain>".
  • $title: Title of the message.
  • $html: Message content in HTML format.
  • $text: Textual content of the message.
  • $attachments: List of attachments, each represented by an associative array containing the following keys:
    • filename: File name.
    • mimetype: MIME type of the file.
    • data: Binary content of the file.
  • $cc: Recipient copied to the message, or list of recipients.
  • $bcc: Recipient in hidden copy, or list of recipients.
  • $unsubscribe: Contents of SMTP List-Unsubscribe header.
  • $envelopeSender: Sender address sent to sendmail.

Example:

// sender, recipient and title of the message
$from = 'vader@empire.com';
$to = 'luke@rebellion.org';
$title = 'Hi kid';
// HTML and raw text forms of the message
$html = "<h1>Yep</h1><p>I'm your father</p>";
$text = "Yep. I'm your father";
// attached file
$attachments = [
    [
        'filename' => 'come_to_the_dark_side.pdf',
        'mimetype' => 'application/pdf',
        'data'     => file_read_contents('registration_form.pdf'),
    ],
];
// object instantiation
$email = $this->_loader['\Temma\Utils\Email'];
// send the message
$email->mimeMail($from, $to, $title, $html, $text, $attachments);

3.3templatedMail()

This method allows you to send emails in plain text and/or HTML, possibly with attachments. Text and HTML messages are generated from Smarty templates and data passed to the templates.

Method signature:

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

Parameters:

  • $from: Sender of the message, in the form "address@domain" or "Name <address@domain>".
  • $to: Recipient of the message, in the form "address@domain" or "Nom <address@domain>".
  • $title: Title of the message.
  • $htmlTplPath: Path to HTML template.
    Can be an absolute path or a path relative to the project's templates/ directory.
  • $text: Path to template in text format.
    Can be an absolute path or a path relative to the project's templates/ directory.
  • $templateData: Associative array containing data to be transmitted to templates.
  • $attachments: List of attachments, each represented by an associative array containing the following keys:
    • filename: File name.
    • mimetype: MIME type of the file.
    • data: Binary content of the file.
  • $cc: Recipient copied to the message, or list of recipients.
  • $bcc: Recipient in hidden copy, or list of recipients.
  • $unsubscribe: Contents of SMTP List-Unsubscribe header.
  • $envelopeSender: Sender address sent to sendmail.

Example:

// sender, recipient and title of the message
$from = 'vader@empire.com';
$to = 'luke@rebellion.org';
$title = 'Hi kid';
// path to HTML and raw text templates
$htmlTpl = 'emails/message_pour_luke/html.tpl';
$textTpl = 'emals/message_pour_luke/text.tpl';
// template data
$data = [
    'name'   => 'Luky',
    'weapon' => 'Lightsaber',
];
// attached file
$attachments = [
    [
        'filename' => 'come_to_the_dark_side.pdf',
        'mimetype' => 'application/pdf',
        'data'     => file_read_contents('registration_form.pdf'),
    ],
];
// object instantiation
$email = $this->_loader['\Temma\Utils\Email'];
// send the message
$email->templatedMail($from, $to, $title, $htmlTpl, $textTpl, $data, $attachments);

3.4Configuration file

The textMail(), mimeMail() and templatedMail() methods are affected by values that can be set in the etc/temma.php file. This makes it possible, for example, to force recipients to be copied for all messages sent. 

<?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',
    ]
];
  • Line 5 : By adding the disabled parameter and setting it to true, you completely disable the sending of emails.
  • Line 6 : List of domains to which messages can be sent.
  • Line 7: Recipient added as carbon copy. This variable can take a character string containing a recipient (of the form "address@domain.com" or "Name <address@domain.com>", or a list of recipients.
  • Line 8: Recipients added in blind copy. This variable can take a string containing a recipient (of the form "address@domain.com" or "Name <address@domain.com>", or a list of recipients.
  • Line 12: Definition of the address sent as "envelope-sender" (also called "return path") in SMTP headers. This may be necessary in the case of SMTP relays.

3.5Configuration methods

Methods can be used to modify the behavior of the textMail(), mimeMail() and templatedMail() methods. These methods overwrite any values defined in the configuration file. 

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

// disable all mailings
$email->enable(false);
// reactivate
$email->enable(true);

// define authorized domain names
$email->setAllowedDomains(['temma.net', 'github.com']);

// add a copy recipient
$email->setCc('contact@monsupersiteweb.com');
// add multiple recipients to copy
$email->setCc(['aa@bb.com', 'yy@zz.com']);

// add one recipient as blind copy
$email->setBcc('aa@bb.com');
// add several recipients as blind copies
$email->setBcc(['aa@bb.com', 'yy@zz.com']);

// set SMTP envelope-sender header
$email->setEnvelopeSender('administrator@blackstar.com');