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

3.1textMail()

This method requires the object to be instantiated via the dependency injection component. It can be used to send simple plain-text messages.

This method uses any parameters defined in the configuration (see below).

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 requires the object to be instantiated via the dependency injection component. It can be used to send plain text and/or HTML e-mails, with attachments if required.

This method uses any parameters defined in the configuration (see below).

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

The textMail() and mimeMail() 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. 

[
    '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 3 : By adding the disabled parameter and setting it to true, you completely disable the sending of emails.
  • Line 4 : List of domains to which messages can be sent.
  • Line 5: 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 6: 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 10: 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.