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 phpmailer class that allows sending all kinds of mail in plain text or HTML, also with attachments.
| version | 3.0.0 |
|---|---|
| since | 2.2.0 |
| package | contrexx |
| subpackage | core |
| copyright | CONTREXX CMS - COMVATION AG |
| author | Reto Kohli |
| todo | Test! |
adminView($section, $group)
available(string $key, integer $lang_id) : boolean
Mind that {@see init()} should have been called before, setting up the data in all languages you're about to test. Returns false on failure.
stringThe MailTemplate key
integerThe language ID
booleanTrue if the key is available in that
language, false otherwiseclearEmptyPlaceholders(string $value)
stringThe string, by reference
deleteTemplate($section, string $key) : boolean
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.
stringThe optional template key
booleanTrue on success, false otherwiseedit(mixed $section, string $key, $useDefaultActs) : \Cx\Core\Html\Sigma
Stores the MailTemplate if the 'bsubmit' parameter has been posted. If the $key argument is empty, tries to pick the value from $_REQUEST['key'].
mixedThe section of the mail template to be edited
stringThe optional key of the mail template to be edited
\Cx\Core\Html\SigmaThe template objecterrorHandler() : boolean
booleanFalse. Always.get(integer $section, string $key, integer $lang_id) : 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.
| global | ADONewConnection |
|---|---|
| static | |
| author | Reto Kohli |
integerThe optional module ID
stringThe key identifying the template
integerThe optional language ID
mixedThe mail template array on success,
null otherwisegetArray(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : 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.
integerThe section
integerThe optional language ID
stringThe optional sorting order string, SQL syntax
integerThe optional position offset, defaults to zero
integerThe optional limit for returned templates. Defaults to -1 (no limit)
integerThe actual count of templates available in total, by reference
mixedThe template array on success,
null otherwisegetEmpty(string $key) : array
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.
stringThe optional key
arrayThe MailTemplate arrayinit(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : boolean
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 SettingDb}.
integerThe section
integerThe optional language ID
stringThe optional sorting order string, SQL syntax
integerThe optional position offset, defaults to zero
integerThe optional limit for returned templates
integerThe actual count of templates available in total, by reference
booleanTrue on success, false otherwiseoverview(string $section, string $group, integer $limit, $useDefaultActs) : \Cx\Core\Html\Sigma
If empty, the $limit defaults to the "numof_mailtemplate_per_page_backend" setting for the given section and group.
stringThe section
stringThe group
integerThe optional limit for the number of templates to be shown
\Cx\Core\Html\SigmaThe template objectsend(array $arrField) : boolean
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 name. If the keys are numeric, the values are regarded as paths. inline An array of inline (image) file paths to attach. If this is used, HTML mode is switched on automatically. 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 {@see 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 {@see File} class version 2.2.0.
| static | |
|---|---|
| author | Reto Kohli |
arrayThe array of template fields
booleanTrue if the mail could be sent,
false otherwisestore(string $section, array $arrField) : boolean
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 attachments 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. 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: The attachment paths must comply with the requirements for file paths as defined in the {@see File} class version 2.2.0.
stringThe section
arrayThe field array
booleanTrue on success, false otherwisestoreFromPost(string $section) : boolean
Sets appropriate messages.
stringThe section
booleanTrue on success, null if nothing
needs storing, false otherwisesubstitute(string $string, array $substitution)
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 replace any blocks or placeholders from the string that have not been substituted, call {@see clearEmptyPlaceholders()} after all values have been substituted. This will take care both of unused blocks and placeholders. See {@see send()} for an example.
stringThe string to be searched and replaced, by reference
arrayThe array of placeholders and values, by reference
$arrTemplates : array
$empty : array
$section : integer
$text
TEXT_ATTACHMENTS
TEXT_BCC
TEXT_CC
TEXT_FROM
TEXT_INLINE
TEXT_MESSAGE
TEXT_MESSAGE_HTML
TEXT_NAME
TEXT_REPLY
TEXT_SENDER
TEXT_SUBJECT
TEXT_TO