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!

 Methods

adminView()

adminView($section, $group) 
Static

Parameters

$section

$group

Converts the attachment string from the database table into an array, if necessary

attachmentsToArray(mixed $attachments) : array
Static

If the parameter value is an array already, it is returned unchanged. If the parameter value is a string, it MUST be in one of the forms 'return array();' or 'return array(index => "path/filename");' or 'return array("path" => "filename");' with zero or more entries containing at least the "filename" as value and an optional path as key. "path" MUST be either a path relative to the document root (including the file name), or a numeric key. If "path" is numeric, it will be ignored and the "filename" will be used. In this case, "filename" itself needs to contain the path to the attachment. The third form allows you to specify a file name different from the original provided in "path" to be used for the e-mail.

Parameters

$attachments

mixed

The attachment string or array

Returns

arrayThe attachment array on success, the empty array otherwise

Returns true if the template for the key exists and is available in that language

available(string $key, integer $lang_id) : boolean
Static

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.

Parameters

$key

string

The MailTemplate key

$lang_id

integer

The language ID

Returns

booleanTrue if the key is available in that language, false otherwise

Removes left over placeholders and blocks from the string

clearEmptyPlaceholders(string $value) 
Static

Parameters

$value

string

The string, by reference

Delete the template with the given key

deleteTemplate($section, string $key) : boolean
Static

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

$key

string

The optional template key

Returns

booleanTrue on success, false otherwise

Show the selected mail template for editing

edit(mixed $section, string $key, $useDefaultActs) : \Cx\Core\Html\Sigma
Static

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

Returns

\Cx\Core\Html\SigmaThe template object

Handles many problems caused by the database table

errorHandler() : boolean
Static

Returns

booleanFalse. Always.

Returns the selected mail template and associated fields from the database.

get(integer $section, string $key, integer $lang_id) : mixed
Static

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

Parameters

$section

integer

The optional module ID

$key

string

The key identifying the template

$lang_id

integer

The optional language ID

Returns

mixedThe mail template array on success, null otherwise

Returns the complete array of templates available for the selected language and module.

getArray(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : mixed
Static

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

integer

The section

$lang_id

integer

The optional language ID

$order

string

The optional sorting order string, SQL syntax

$position

integer

The optional position offset, defaults to zero

$limit

integer

The optional limit for returned templates. Defaults to -1 (no limit)

$count

integer

The actual count of templates available in total, by reference

Returns

mixedThe template array on success, null otherwise

Returns a new, empty MailTemplate

getEmpty(string $key) : array
Static

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

Returns

arrayThe MailTemplate array

Initialize the mail template array for the current module

init(integer $section, integer $lang_id, string $order, integer $position, integer $limit, integer $count) : boolean
Static

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}.

Parameters

$section

integer

The section

$lang_id

integer

The optional language ID

$order

string

The optional sorting order string, SQL syntax

$position

integer

The optional position offset, defaults to zero

$limit

integer

The optional limit for returned templates

$count

integer

The actual count of templates available in total, by reference

Returns

booleanTrue on success, false otherwise

Show on overview of the mail templates for the given section and group

overview(string $section, string $group, integer $limit, $useDefaultActs) : \Cx\Core\Html\Sigma
Static

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

integer

The optional limit for the number of templates to be shown

$useDefaultActs

Returns

\Cx\Core\Html\SigmaThe template object

Reset the class

reset() 
Static

Forces a call to init() the next time content is accessed

Set up and send an email

send(array $arrField) : boolean
Static

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

Parameters

$arrField

array

The array of template fields

Returns

booleanTrue if the mail could be sent, false otherwise

Update or add a new template

store(string $section, array $arrField) : boolean
Static

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.

Parameters

$section

string

The section

$arrField

array

The field array

Returns

booleanTrue on success, false otherwise

Stores a template after editing

storeFromPost(string $section) : boolean
Static

Sets appropriate messages.

Parameters

$section

string

The section

Returns

booleanTrue on success, null if nothing needs storing, false otherwise

Substitutes the placeholders found in the $substitution array in $value

substitute(string $string, array $substitution) 
Static

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.

Parameters

$string

string

The string to be searched and replaced, by reference

$substitution

array

The array of placeholders and values, by reference

 Properties

 

$arrTemplates : array
 

$empty : array
 

$section : integer
 

$text 

 Constants

 

Class constant for the mail template attachments Text key

TEXT_ATTACHMENTS 
 

Class constant for the mail template bcc Text key

TEXT_BCC 
 

Class constant for the mail template cc Text key

TEXT_CC 
 

Class constant for the mail template from Text key

TEXT_FROM 
 

Class constant for the mail template inline Text key

TEXT_INLINE 
 

Class constant for the mail template message plain Text key

TEXT_MESSAGE 
 

Class constant for the mail template message HTML Text key

TEXT_MESSAGE_HTML 
 

Class constant for the mail template name Text key

TEXT_NAME 
 

Class constant for the mail template reply Text key

TEXT_REPLY 
 

Class constant for the mail template sender Text key

TEXT_SENDER 
 

Class constant for the mail template subject Text key

TEXT_SUBJECT 
 

Class constant for the mail template to Text key

TEXT_TO 
© Copyright 2014 by Comvation AG
Generated on 2014-07-11T08:39:25+02:00.