MailTemplate
in package
Core Mail and Template Class
Manages e-mail templates in any language, accessible by module and key for easy access. Includes a nice wrapper for the \Cx\Core\MailTemplate\Model\Entity\Mail that allows sending all kinds of mail in plain text or HTML, also with attachments.
Tags
Table of Contents
Constants
- TEXT_ATTACH_PDF = 'core_mail_template_attach_pdf'
- Class constant for Attach dynamic PDF-document Text key
- TEXT_ATTACHMENTS = 'core_mail_template_attachments'
- Class constant for the mail template attachments Text key
- TEXT_BCC = 'core_mail_template_bcc'
- Class constant for the mail template bcc Text key
- TEXT_CC = 'core_mail_template_cc'
- Class constant for the mail template cc Text key
- TEXT_FROM = 'core_mail_template_from'
- Class constant for the mail template from Text key
- TEXT_INLINE = 'core_mail_template_inline'
- Class constant for the mail template inline Text key
- TEXT_MESSAGE = 'core_mail_template_message'
- Class constant for the mail template message plain Text key
- TEXT_MESSAGE_HTML = 'core_mail_template_message_html'
- Class constant for the mail template message HTML Text key
- TEXT_NAME = 'core_mail_template_name'
- Class constant for the mail template name Text key
- TEXT_PDF_TEMPLATE = 'core_mail_template_pdf_template'
- Class constant for PDF template id Text key
- TEXT_REPLY = 'core_mail_template_reply'
- Class constant for the mail template reply Text key
- TEXT_SENDER = 'core_mail_template_sender'
- Class constant for the mail template sender Text key
- TEXT_SUBJECT = 'core_mail_template_subject'
- Class constant for the mail template subject Text key
- TEXT_TO = 'core_mail_template_to'
- Class constant for the mail template to Text key
Properties
- $arrCachedTemplates : array<string|int, mixed>
- $arrTemplates : array<string|int, mixed>
- The array of mail templates loaded in {@see init()}
- $empty : array<string|int, mixed>
- An empty template
- $section : int
- The module ID used when init() was called
- $text : mixed
Methods
- adminView() : Sigma|null
- Show on adminview of the mail templates for the given section and group
- available() : bool
- Returns true if the template for the key exists and is available in that language
- clearEmptyPlaceholders() : mixed
- Removes left over placeholders and blocks from the string
- deleteTemplate() : bool
- Delete the template with the given key
- edit() : Sigma
- Show the selected mail template for editing
- errorHandler() : bool
- Handles many problems caused by the database table
- get() : mixed
- Returns the selected mail template and associated fields from the database.
- getArray() : mixed
- Returns the complete array of templates available for the selected language and module.
- getEmpty() : array<string|int, mixed>
- Returns a new, empty MailTemplate
- getSenderDomains() : array<string|int, mixed>
- Get used sender domains of a component
- init() : bool
- Initialize the mail template array for the current module
- overview() : Sigma
- Show on overview of the mail templates for the given section and group
- reset() : mixed
- Reset the class
- send() : bool
- Set up and send an email
- sendTestMail() : mixed
- store() : bool
- Update or add a new template
- storeFromPost() : bool
- Stores a template after editing
- substitute() : mixed
- Substitutes the placeholders found in the $substitution array in $value
- getDomainFromEmail() : string
- Get the domain of email address $email
- linkSenderDomainUsages() : array<string|int, mixed>
- Helper for {@see static::getSenderDomains()} to link sender domain usages to each component's specific target URL.
Constants
TEXT_ATTACH_PDF
Class constant for Attach dynamic PDF-document Text key
public
mixed
TEXT_ATTACH_PDF
= 'core_mail_template_attach_pdf'
TEXT_ATTACHMENTS
Class constant for the mail template attachments Text key
public
mixed
TEXT_ATTACHMENTS
= 'core_mail_template_attachments'
TEXT_BCC
Class constant for the mail template bcc Text key
public
mixed
TEXT_BCC
= 'core_mail_template_bcc'
TEXT_CC
Class constant for the mail template cc Text key
public
mixed
TEXT_CC
= 'core_mail_template_cc'
TEXT_FROM
Class constant for the mail template from Text key
public
mixed
TEXT_FROM
= 'core_mail_template_from'
TEXT_INLINE
Class constant for the mail template inline Text key
public
mixed
TEXT_INLINE
= 'core_mail_template_inline'
TEXT_MESSAGE
Class constant for the mail template message plain Text key
public
mixed
TEXT_MESSAGE
= 'core_mail_template_message'
TEXT_MESSAGE_HTML
Class constant for the mail template message HTML Text key
public
mixed
TEXT_MESSAGE_HTML
= 'core_mail_template_message_html'
TEXT_NAME
Class constant for the mail template name Text key
public
mixed
TEXT_NAME
= 'core_mail_template_name'
TEXT_PDF_TEMPLATE
Class constant for PDF template id Text key
public
mixed
TEXT_PDF_TEMPLATE
= 'core_mail_template_pdf_template'
TEXT_REPLY
Class constant for the mail template reply Text key
public
mixed
TEXT_REPLY
= 'core_mail_template_reply'
TEXT_SENDER
Class constant for the mail template sender Text key
public
mixed
TEXT_SENDER
= 'core_mail_template_sender'
TEXT_SUBJECT
Class constant for the mail template subject Text key
public
mixed
TEXT_SUBJECT
= 'core_mail_template_subject'
TEXT_TO
Class constant for the mail template to Text key
public
mixed
TEXT_TO
= 'core_mail_template_to'
Properties
$arrCachedTemplates
protected
static array<string|int, mixed>
$arrCachedTemplates
= []
$arrTemplates
The array of mail templates loaded in {@see init()}
private
static array<string|int, mixed>
$arrTemplates
= null
$empty
An empty template
private
static array<string|int, mixed>
$empty
= array('key' => null, 'name' => null, 'from' => null, 'sender' => null, 'reply' => null, 'to' => null, 'cc' => null, 'bcc' => null, 'subject' => null, 'message' => null, 'message_html' => null, 'attachments' => array(), 'inline' => array(), 'protected' => false, 'html' => false, 'available' => false, 'attach_pdf' => false, 'pdf_template' => null)
$section
The module ID used when init() was called
private
static int
$section
= null
$text
private
static mixed
$text
= array('name' => self::TEXT_NAME, 'from' => self::TEXT_FROM, 'sender' => self::TEXT_SENDER, 'reply' => self::TEXT_REPLY, 'to' => self::TEXT_TO, 'cc' => self::TEXT_CC, 'bcc' => self::TEXT_BCC, 'subject' => self::TEXT_SUBJECT, 'message' => self::TEXT_MESSAGE, 'message_html' => self::TEXT_MESSAGE_HTML, 'attach_pdf' => self::TEXT_ATTACH_PDF, 'pdf_template' => self::TEXT_PDF_TEMPLATE)
Methods
adminView()
Show on adminview of the mail templates for the given section and group
public
static adminView(string $section[, string $group = 'nonempty' ][, int $limit = 0 ][, string $act = 'mailtemplate_overview' ][, array<string|int, mixed> $placeholders = array() ]) : Sigma|null
Parameters
- $section : string
-
The section
- $group : string = 'nonempty'
-
The group default set to nonempty
- $limit : int = 0
-
The optional limit for the number of templates to get listed per page
- $act : string = 'mailtemplate_overview'
-
The action of the mail template default set to mailtemplate_overview
- $placeholders : array<string|int, mixed> = array()
Return values
Sigma|null —The template object or null if section cannot be loaded
available()
Returns true if the template for the key exists and is available in that language
public
static available(string $key, int $lang_id) : bool
Mind that init() should have been called before, setting up the data in all languages you're about to test. Returns false on failure.
Parameters
- $key : string
-
The MailTemplate key
- $lang_id : int
-
The language ID
Return values
bool —True if the key is available in that language, false otherwise
clearEmptyPlaceholders()
Removes left over placeholders and blocks from the string
public
static clearEmptyPlaceholders(string &$value) : mixed
Parameters
- $value : string
-
The string, by reference
deleteTemplate()
Delete the template with the given key
public
static deleteTemplate(mixed $section[, string $key = '' ]) : bool
Protected (system) templates can not be deleted. Deletes all languages available. if the $key argument is left out, looks for a key in the delete_mailtemplate_key index of the $_REQUEST array.
Parameters
- $section : mixed
- $key : string = ''
-
The optional template key
Return values
bool —True on success, false otherwise
edit()
Show the selected mail template for editing
public
static edit(mixed $section[, string $key = '' ][, mixed $useDefaultActs = true ][, string $act = 'mailtemplate_overview' ][, array<string|int, mixed> $placeholders = array() ]) : Sigma
Do not use directly. Use adminView() instead.
Stores the MailTemplate if the 'bsubmit' parameter has been posted. If the $key argument is empty, tries to pick the value from $_REQUEST['key'].
Parameters
- $section : mixed
-
The section of the mail template to be edited
- $key : string = ''
-
The optional key of the mail template to be edited
- $useDefaultActs : mixed = true
- $act : string = 'mailtemplate_overview'
-
The action of the mail template
- $placeholders : array<string|int, mixed> = array()
Return values
Sigma —The template object
errorHandler()
Handles many problems caused by the database table
public
static errorHandler() : bool
Return values
bool —False. Always.
get()
Returns the selected mail template and associated fields from the database.
public
static get(int $section, string $key[, int $lang_id = null ]) : mixed
The $key parameter uniquely identifies the template for each module. The optional $lang_id may be provided to override the language ID present in the global FRONTEND_LANG_ID constant.
Parameters
- $section : int
-
The optional module ID
- $key : string
-
The key identifying the template
- $lang_id : int = null
-
The optional language ID
Tags
Return values
mixed —The mail template array on success, null otherwise
getArray()
Returns the complete array of templates available for the selected language and module.
public
static getArray(int $section[, int $lang_id = null ][, string $order = null ][, int $position = 0 ][, int $limit = -1 ][, int &$count = 0 ]) : mixed
If the optional $lang_id argument is empty, the current language ID, or the global FRONTEND_LANG_ID constant is used instead, in this order.
Parameters
- $section : int
-
The section
- $lang_id : int = null
-
The optional language ID
- $order : string = null
-
The optional sorting order string, SQL syntax
- $position : int = 0
-
The optional position offset, defaults to zero
- $limit : int = -1
-
The optional limit for returned templates. Defaults to -1 (no limit)
- $count : int = 0
-
The actual count of templates available in total, by reference
Return values
mixed —The template array on success, null otherwise
getEmpty()
Returns a new, empty MailTemplate
public
static getEmpty([string $key = '' ]) : array<string|int, mixed>
Note that this is NOT a constructor, but a static method that returns an empty template array with all fields empty, with the exception of the optional $key.
Parameters
- $key : string = ''
-
The optional key
Return values
array<string|int, mixed> —The MailTemplate array
getSenderDomains()
Get used sender domains of a component
public
static getSenderDomains(string $componentName, Url $target) : array<string|int, mixed>
Parameters
- $componentName : string
-
Name of component to fetch the used sender domains from
- $target : Url
-
Target url to be used for
editurlofusages
Return values
array<string|int, mixed>init()
Initialize the mail template array for the current module
public
static init(int $section[, int $lang_id = null ][, string $order = '' ][, int $position = 0 ][, int $limit = -1 ][, int &$count = 0 ]) : bool
Uses the given language ID $lang_id if not empty, or all active frontend languages otherwise. The $limit value defaults to the value of the mailtemplate_per_page_backend setting from the core settings (@see \Cx\Core\Setting\Controller\Setting}.
Parameters
- $section : int
-
The section
- $lang_id : int = null
-
The optional language ID
- $order : string = ''
-
The optional sorting order string, SQL syntax
- $position : int = 0
-
The optional position offset, defaults to zero
- $limit : int = -1
-
The optional limit for returned templates
- $count : int = 0
-
The actual count of templates available in total, by reference
Return values
bool —True on success, false otherwise
overview()
Show on overview of the mail templates for the given section and group
public
static overview(string $section, string $group[, int $limit = 0 ][, mixed $useDefaultActs = true ][, string $act = 'mailtemplate_edit' ]) : Sigma
Do not use directly. Use adminView() instead.
If empty, the $limit defaults to the "numof_mailtemplate_per_page_backend" setting for the given section and group.
Parameters
- $section : string
-
The section
- $group : string
-
The group
- $limit : int = 0
-
The optional limit for the number of templates to be shown
- $useDefaultActs : mixed = true
- $act : string = 'mailtemplate_edit'
-
The action of the mail template default set to mailtemplate_overview
Return values
Sigma —The template object
reset()
Reset the class
public
static reset() : mixed
send()
Set up and send an email
public
static send(array<string|int, mixed> $arrField) : bool
The array argument is searched for the following indices: key The key of any mail template to be used section The module to initialize for (mandatory when key is set) sender The sender name from The sender e-mail address to The recipient e-mail address(es), comma separated reply The reply-to e-mail address cc The carbon copy e-mail address(es), comma separated bcc The blind carbon copy e-mail address(es), comma separated subject The message subject message The plain text message body message_html The HTML message body html If this evaluates to true, turns on HTML mode attachments An array of file paths to attach. The array keys may be used for the paths and the values for the display names. If the keys are numeric, the values are regarded as paths and the paths filename's will be used as display names. inline An array of inline (image) file paths to attach. If this is used, HTML mode is switched on automatically. Uses same array notation as 'attachments'. search The array of patterns to be replaced by... replace The array of replacements for the patterns substitution A more complex structure for replacing placeholders and/or complete blocks, conditionally or repeatedly. If the key index is present, the corresponding mail template is loaded first. Other indices present (sender, from, to, subject, message, etc.) will override the template fields. Missing mandatory fields are filled with the default values from the global $_CONFIG array (sender, from, to), or some core language variables (subject, message). A simple str_replace() is used for the search and replace operation, and the placeholder names are quoted in the substitution, so you cannot use regular expressions. More complex substitutions including repeated blocks may be specified in the substitution subarray of the $arrField parameter value. The e-mail addresses in the To: field will be used as follows:
- Groups of addresses are separated by semicola (;)
- Single addresses are separated by comma (,) All recipients of any single group are added to the To: field together, Groups are processed separately. So, if your To: looks like a@a.com,b@b.com;c@c.com,d@d.com a total of two e-mails will be sent; one to a and b, and a second one to c and d. Addresses for copies (Cc:) and blind copies (Bcc:) are added to all e-mails sent, so if your e-mail is in the Cc: or Bcc: field in the example above, you will receive two copies. Note: The attachment paths must comply with the requirements for file paths as defined in the File class version 2.2.0.
Parameters
- $arrField : array<string|int, mixed>
-
The array of template fields
Tags
Return values
bool —True if the mail could be sent, false otherwise
sendTestMail()
public
static sendTestMail(mixed $section, mixed $key, mixed $email) : mixed
Parameters
- $section : mixed
- $key : mixed
- $email : mixed
store()
Update or add a new template
public
static store(string $section, array<string|int, mixed> $arrField) : bool
Stores the template for the given section Uses the language ID from the lang_id index, if present, or the FRONTEND_LANG_ID constant otherwise. key The key of any mail template to be used lang_id The language ID sender The sender name from The sender e-mail address to The recipient e-mail address(es), comma separated reply The reply-to e-mail address cc The carbon copy e-mail address(es), comma separated bcc The blind carbon copy e-mail address(es), comma separated subject The message subject message The plain text message body message_html The HTML message body html If this evaluates to true, turns on HTML mode The key index is mandatory. If available, the corresponding mail template is loaded, and updated. Missing fields are filled with default values, which are generally empty. The protected flag can neither be set nor cleared by calling this method, but is always kept as-is. Note: Storing attachments (and inline) is not suppored. Attachments (and inline) must directly be supplied as arguments to method send().
Parameters
- $section : string
-
The section
- $arrField : array<string|int, mixed>
-
The field array
Return values
bool —True on success, false otherwise
storeFromPost()
Stores a template after editing
public
static storeFromPost(string $section) : bool
Sets appropriate messages.
Parameters
- $section : string
-
The section
Return values
bool —True on success, null if nothing needs storing, false otherwise
substitute()
Substitutes the placeholders found in the $substitution array in $value
public
static substitute(string &$string, array<string|int, mixed> &$substitution[, bool $convertToHtmlEntities = false ][, bool $clearEmptyPlaceholders = true ]) : mixed
Each array key in $substitution is regarded as a placeholder name. Each name is enclosed in square brackets ("[", "]") to form the full placeholder. If its value is an array, it represents a repeatable block with contents in an (indexed) array, otherwise it's a simple replacement.
Your template $string might look something like
A single [PLACEHOLDER] is substituted here once.
[[BLOCK]This line is repeated for each [ITEM] in the block.[BLOCK]] If there is no [ITEM] in the BLOCK subarray, the block is never parsed and thus removed.
The $substitution array looks like array( 'PLACEHOLDER' => 'Scalar replacement value', 'BLOCK' => array( index => array( 'ITEM' => 'Another scalar value', 'MORE_PLACEHOLDERS_OR_BLOCKS' => 'Nest as deep as memory allows', ... more ... ), ... more ... ), ... more ... )
Of course, all names used above are just examples, any block or placeholder name may be an arbitrary word consisting of letters and underscores.
Any block may occur more than once. Its contents are repeated. Each block name MUST occur an even number of times in the string.
Mind that the names in the substitution array SHOULD be unique, or the order of the elements becomes relevant and the results may not be what you expect! The array is processed depth-first, so every time a block array is encountered, it is completely substituted recursively before the next value is even looked at.
Final note: To skip replacing any blocks or placeholders from the string that have not been substituted, set $clearEmptyPlaceholders to false have been substituted. This will take care both of unused blocks and placeholders. See send() for an example.
Parameters
- $string : string
-
The string to be searched and replaced, by reference
- $substitution : array<string|int, mixed>
-
The array of placeholders and values, by reference
- $convertToHtmlEntities : bool = false
-
if true, converts the values to html entities
- $clearEmptyPlaceholders : bool = true
-
If set to false does not clear empty blocks and placeholders
getDomainFromEmail()
Get the domain of email address $email
protected
static getDomainFromEmail(string $email) : string
If $email is an empty string or not a valid email address then the domain of the basic setting coreAdminEmail is returned.
Parameters
- $email : string
-
Email to fetch the domain from
Return values
string —Domain part of email
linkSenderDomainUsages()
Helper for {@see static::getSenderDomains()} to link sender domain usages to each component's specific target URL.
protected
static linkSenderDomainUsages(array<string|int, mixed> $senderDomains, Url $target) : array<string|int, mixed>
Parameters
- $senderDomains : array<string|int, mixed>
-
List of sender domains
- $target : Url
-
Target url to be used for
editurlofusages