Documentation
Email helper
Table of Contents ▼
Presentation
Helper for sending emails, with the option of sending simple plain text messages, or more complex messages (HTML and text format, attachments).
The \Temma\UtilsEmail 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 temma.json 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.
Static methods
simpleMail()
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?");
fullMail()
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>");
Object-oriented methods
textMail()
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);
mimeMail()
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);
Configuration
The textMail() and mimeMail() methods are affected by values that can be set in the temma.json 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.
Previous: | DataFilter helpers |
Next: | HTMLCleaner helper |
Table of Contents
- Migration : How to upgrade from Temma 1.x to version 2
- Installation : Download Temma and install it to start your web project
- Configuration : All the configuration directives of the etc/temma.json file and the optional environment variables
- External libraries : How to use external function libraries
- Routing : Temma's default routing system, and advanced routing
- Log : Use of the log system, management by criticality levels
- Controllers : Essential parts of your web application
- Views : Smarty templates or JSON/CSV/RSS/iCal/INI exports
- Dependency injection : The backbone of your application developments
- Sessions : Extension of user sessions managed by PHP
- Data sources : Unified data access management
- Model : How to use DAOs to access databases
- Execution flow : How to manage the execution flow, between plugins and the controller
- Plugins : How to use plugins, and create your own plugins to modularize your code
- Attributes : How to filter access to controllers and actions
- Tests : To write automated integration tests.
- Command-line interface : To create executable scripts on the command line, automatically initialized by Temma
-
Helpers :
Items offered by Temma to help you in various circumstances
- Command-line scripts
-
Controller + plugin
- Auth : Controller and plugin to manage user authentication
- Plugins
- Attributes
-
Smarty plugins
- urlize : Modifier to transform a text into an URL
- filenamize : Modifier to transform a text into a file name
- nbsp : Modifier to transform spaces into non-breakable spaces
-
Utility objects
- ANSI : To format texts written to standard output
- BaseConvert : To do digital base conversions
- DataFilter : To filter and validate data
- Email : To send emails
- HTMLCleaner : To clean up an HTML stream coming from a WYSIWYG editor
- IniExport : To export data in INI format
- Json : To read JSON streams that may contain comments
- Lock : To lock access to a file, or the execution of the current PHP script
- Registry : To properly store global variables
- Smarty : To process Smarty templates outside the view
- Term : Terminal management (TTY)
- Text : Different treatments on character strings
- Timer : To manage stopwatches