Docs For Class midcom_helper

Description

This is a E-Mail template engine. It basically takes a template out of a mailtemplate datamanager field, fills it in with the parameters that have been set and sends it using the PEAR Mail classes.

Prerequisites

PEAR Package: Mail
PEAR Package: Mail_mime

E-Mail template language

Four types of variables can be inserted into the E-Mail's subject or body. Every value has an associated key, which is searched as array key in the parameter array. Key-Names are matched case-sensitive. Note, that of course the double-quotes in the identifier examples are only to distinguish them from the flowed text.

String values

They are identified by "__KEY__" and are inserted directly. There is no line wrapping.

2. Associative arrays

If you want to pass an array as parameter, ensure, that both key and value are convertible to a string by PHP implicitly. Ideally, you have only strings, of course. In the following example, "KEY" refers to the key of the array within the parameter array, and "SUBKEY" refers to the key of a value within the actual array.

Again, you can access the (whole) array using "__KEY__". In that case you will get a formatted output of all keys and values, consisting of "SUBKEY: VALUE" entries. The value gets word-wrapped and indented automatically at about 76 chars to keep the output easily readable.

If you want to access a specific value from this array, you have to use "__KEY_SUBKEY__" to identify it. This syntax is treated like a string value.

3. Generic objects

You can pass any object as a value. In this case, the same semantic as with an Array can be used to access the object: "__KEY__" will give you a complete dump, while "__KEY_SUBKEY__" accesses a specific property.

The complete dump will omit all properties that are prefixed with an "_"; according to the MidCOM namespace conventions, these are private members of a class and should not be touched. You can still access them with the direct indexer, though this is strongly discouraged within a MidCOM context. Also note, that variables with more then one underscore as a prefix might cause trouble with the regular expression used to parse the template.

4. Datamanager objects

This is a special mode, usable to easily interface with the MidCOM datamanager.

Again, this is to be used like an Array value, supporting both "__KEY__" and "__KEY_SUBKEY__". This mode will use the CSV (string-only) representation of the various datatypes as a replacement value. This way even BLOB-Types and the like can be safely put into an E-Mail.

The dump syntax will omit all values tagged as "hidden" or "aisonly", they are accessible through the element indexers though.

Variables with more then one underscore as a prefix might cause trouble with the regular expression used to parse the template, so you should not rely on them.

Character encoding issues

The template engine tries its best to work with the various character encodings it might encounter. For a start, it will try to convert each value into the character set that has been specified in the E-Mail template.

You can avoid many problems, if you specify, what encoding the parameters you pass to the class are in, the set_parameters call has an (optional) parameter for this.

If you omit this, the engine tries to detect the encoding of the values using the Multi-Byte function mb_detect_encoding. If the encoding can't be detected or is one of the ISO-8859-* encoding, it defaults to ISO-8859-15 (Latin-1). Both might very well lead into a really corrupt E-Mail. So try to specify the source encoding, if possible.

Sending Mails

Currently, the engine will send the E-Mails through the PHP mail function, so ensure that it is correctly configured. In the future alternated backends (out of the PEAR Mail packages) might become available through MidCOM.

Example usage code

$template = new midcom_helper_mailtemplate($this->_config_dm->data["mail_newreservation"]);
$parameters = Array(
"RESOURCE" => $this->_resource->dm,
"RESERVATION" => $this->dm,
"ISOSTART" => $this->dm->data["start"]["strfulldate"],
"ISOEND" => $this->dm->data["end"]["strfulldate"],
"LOCALSTART" => $this->dm->data["start"]["local_strfulldate"],
"LOCALEND" => $this->dm->data["end"]["local_strfulldate"],
);
$template->set_parameters($parameters);
$template->parse();
$failed = $template->send($this->dm->data["email"]);
if ($failed > 0)
{
debug_add("$failed E-Mails could not be sent.", MIDCOM_LOG_WARN);
}

This code could for example use a Template subject / body like this:

 Subject: New Reservation for __RESOURCE_name__

 Your reservation has been received, you will receive a confirmation E-Mail shortly:

 Start: __ISOSTART__
 End: __ISOEND__
 __RESERVATION__

Located in /midcom.core/midcom/helper/mailtemplate.php (line 135)

Variable Summary

int $failed

int $sent

Method Summary

midcom_helper_mailtemplate midcom_helper_mailtemplate (Array $template)

Array get_parameters ()

string get_parameters_encoding ()

void parse ()

boolean send (mixed $to)

void set_parameters (Array $parameters, [string $encoding = null])

Variables

int $failed (line 218)

Number of E-Mails that failed sending.

Note, that due to the design of the PEAR Mime classes, this is not reliably.

int $sent (line 209)

Number of E-Mails sent successfully.

Note, that due to the design of the PEAR Mime classes, this is not reliably.

Methods

Constructor midcom_helper_mailtemplate (line 235)

Constructs the template engine on the base of the passed template.

This will load the pear modules Mail and Mail_Mime.

midcom_helper_mailtemplate midcom_helper_mailtemplate (Array $template)

Array $template: The value of a Datamanager mailtemplate type

get_parameters (line 276)

Returns the currently set parameters.

return: Current parameter set.

Array get_parameters ()

get_parameters_encoding (line 286)

Retrieve the current parameter character encoding.

return: The encoding name.

string get_parameters_encoding ()

parse (line 297)

Parses the template and generates the message body and subject.

Internally, it relies heavily on Perl Regular Expressions to replace the template parameters with their values.

void parse ()

send (line 391)

Sends the email to both the addresses specified in the template and the addresses passed through $to. You can either pass a single address as a string or an array of addresses.

This call will complete the headers (Date, X-Mailer etc.) and transmit the E-Mail to all recipients. It will return the number of failed addresses, the details can be queried to the member variable $failed.

A "To:" line will be created accordingly.

If the template has not yet been explicitly parsed, this is done silently.

return: Indicating success.

boolean send (mixed $to)

mixed $to: Recipients, either a single string (one recipient), or an Array of strings (multiple recipients).

set_parameters (line 265)

This will set the template parameters accordingly.

If you omit the encoding, a detection will be attempted (see above). To avoid trouble, try to specify an encoding every time.

void set_parameters (Array $parameters, [string $encoding = null])

Array $parameters: The template parameters.
string $encoding: The character encoding in which $parameters are passed.

Class midcom_helper_mailtemplate