Development Core MailTemplate
MailTemplate component provides mailing capabilities to Cloudrexx.
- Sending e-mails
- Management and usage of e-mail templates having features as:
- Localisation support
- Support for static attachments and dynamically generated PDF documents (by using PDF component)
- Block and placeholder support
- Multipart support (plaintext/html)
The simplest way of sending an email is by just calling
\Cx\Core\MailTemplate\Controller\MailTemplate::send() as follows:
$options = [ 'to' => 'firstname.lastname@example.org', 'subject' => 'Hello World', 'message' => 'This is a plaintext message', ]; \Cx\Core\MailTemplate\Controller\MailTemplate::send($options);
The full list of
$options that can be passed to
send() is as follows:
||The key of any mail template to be used|
||The module to initialize for (mandatory when key is set)|
||The sender name|
||The sender e-mail address|
||The recipient e-mail address(es), comma separated|
||The reply-to e-mail address|
||The carbon copy e-mail address(es), comma separated|
||The blind carbon copy e-mail address(es), comma separated|
||The message subject|
||The plain text message body|
||The HTML message body|
||If this evaluates to |
||An array of file paths to attach. The array keys may be used for the paths, and the values for the name. If the keys are numeric, the values are regarded as paths.|
||An array of inline (image) file paths to attach. If this is used, HTML mode (|
||The array of patterns to be replaced by...|
||The array of replacements for the patterns|
||A more complex structure for replacing placeholders and/or complete blocks, conditionally or repeatedly.|
key has been set, it tries to load the e-mail template identified by
key (see e-mail templates), otherwise a blank email is initialised.
The generated mail will be sent to the recipients defined by
If case of successful e-mail dispatching (to the configured SMTP server), the method
E-mail templates provide the ability for custom tailored e-mail notifications that can be managed by a user over a GUI.
The management of e-mail templates can easily be integrated into a backend section as follows:
$htmlCode = \Cx\Core\MailTemplate\Controller\MailTemplate::overview( $this->getComponent()->getName(), 'config' )->get();
To integrate the management GUI directly into the view of the Setting configuration dialogue, do see separate section.
Sending an e-mail template is as easy as sending a non-template e-mail, with the exception that a
key must be specified that does identify the e-mail template to be sent:
$options = [ 'key' => 'order_confirmation', 'section' => 'Shop', ]; \Cx\Core\MailTemplate\Controller\MailTemplate::send($options);
Any previously defined option by the e-mail template will be overwritten if it gets passed to
MailTemplate e-mail (both a template and non-template e-mail) does support template blocks and placeholders in the following form:
Placeholders (case insensitive): [place_holder], [PLACEHOLDER] or [PLACEHOLDER2] Conditional or repeated blocks: [[BLOCK] ... [PLACEHOLDER] ... [BLOCK]]
When sending an e-mail, the option
substitution can then be used to pass the data that shall be used to parse the placeholders and blocks within an email.
It is important to note, that not only the body (
message) of an email does support placeholders and blocks, but all
$options. Meaning that
substitution will be applied to all set
$options of an e-mail template.
Placeholders and blocks that are empty or not defined by
substitution will be removed from the e-mail before it will be sent.
If the latter is not intended, then instead of
substitution, you could use
search together with
replace which will do a static search & replace on all
$options of an e-mail template.
The following examples will use the following template:
[[MY_BLOCK] ... [MY_PLACEHOLDER] ... [MY_BLOCK]]
[ 'my_block' => [ 0 => [ 'MY_PLACEHOLDER' => 'Hello World' ], ], ]
... Hello World ...
[ 'my_block' => [ 0 => [ 'MY_PLACEHOLDER' => 'One', ], 1 => [ 'MY_PLACEHOLDER' => 'Two', ], ], ]
... One ... ... Two ...
$options['substitution'] = [ 'my_block' => [ 'MY_PLACEHOLDER' => 'Hello World' ], ];
MailTemplate will use the default SMTP server (as set in Administration > Basic Configuration > E-mail Server) for relying mail.
cx envenvironment the SMTP server can be set through the environment variable