CWIS Developer Documentation
List of all members
Email Class Reference

Electronic mail message. More...

Sending

 Send ()
 Mail the message. More...
 
 AddLogData ($LogData)
 Provide additional data that should be included when a message is logged. More...
 
static ToWhitelist ($NewValue=NULL)
 Set whitelist of acceptable recipient addresses. More...
 
static RegisterLoggingFunction ($NewValue)
 Register a logging callback. More...
 

Message Attributes

 Body ($NewValue=NULL)
 Get/set message body. More...
 
 AlternateBody ($NewValue=NULL)
 Get/set the plain-text alternative to the body. More...
 
 Subject ($NewValue=NULL)
 Get/set message subject. More...
 
 From ($NewAddress=NULL, $NewName=NULL)
 Get/set message sender. More...
 
 ReplyTo ($NewAddress=NULL, $NewName=NULL)
 Get/set message "Reply-To" address. More...
 
 To ($NewValue=NULL)
 Get/set message recipient(s). More...
 
 CC ($NewValue=NULL)
 Get/set message CC list. More...
 
 BCC ($NewValue=NULL)
 Get/set message BCC list. More...
 
 AddHeaders ($NewHeaders)
 Specify additional message headers to be included. More...
 
 CharSet ($NewValue=NULL)
 Specify a character encoding for the message. More...
 
static DefaultFrom ($NewValue=NULL)
 Get/set default "From" address. More...
 
static LineEnding ($NewValue=NULL)
 Specify the character sequence that should be used to end lines. More...
 
static WrapHtmlAsNecessary ($Html, $MaxLineLength=998, $LineEnding="\r\n")
 Wrap HTML in an e-mail as necessary to get its lines less than some max length. More...
 
static TestLineEndings ($Value, $LineEnding)
 Test the line endings in a value to see if they all match the given line ending. More...
 
static ConvertHtmlToPlainText ($Html)
 Try as best as possible to convert HTML to plain text. More...
 

Mail Delivery Method

const METHOD_PHPMAIL = 1
 Deliver using PHP's internal mail() mechanism. More...
 
const METHOD_SMTP = 2
 Deliver using SMTP. More...
 
static DeliveryMethod ($NewValue=NULL)
 Get/set mail delivery method. More...
 
static Server ($NewValue=NULL)
 Get/set server for mail delivery. More...
 
static Port ($NewValue=NULL)
 Get/set port number for mail delivery. More...
 
static UserName ($NewValue=NULL)
 Get/set user name for mail delivery. More...
 
static Password ($NewValue=NULL)
 Get/set password for mail delivery. More...
 
static UseAuthentication ($NewValue=NULL)
 Get/set whether to use authentication for mail delivery. More...
 
static DeliverySettings ($NewSettings=NULL)
 Get/set serialized (opaque text) version of delivery settings. More...
 
static DeliverySettingsOkay ()
 Test delivery settings and report their validity. More...
 
static DeliverySettingErrors ()
 Return array with list of delivery setting errors (if any). More...
 
static ConvertHtmlWhiteSpace ($Html, $Aggressive=FALSE, $LineEnding="\r\n")
 Convert horizontal white space with no semantic value to vertical white space when possible. More...
 
static GetTagInfo ($Html, $TagBegin)
 Get the tag name and whether it's a closing tag from a tag that begins at a specific offset within some HTML. More...
 

Detailed Description

Electronic mail message.

Definition at line 14 of file Email.php.

Member Function Documentation

Email::AddHeaders (   $NewHeaders)

Specify additional message headers to be included.

Parameters
array$NewHeadersArray of header lines.

Definition at line 318 of file Email.php.

Email::AddLogData (   $LogData)

Provide additional data that should be included when a message is logged.

Parameters
array$LogDataAssociative array of data.

Definition at line 136 of file Email.php.

Email::AlternateBody (   $NewValue = NULL)

Get/set the plain-text alternative to the body.

Parameters
string$NewValueNew plain-text alternative. (OPTIONAL)
Returns
Returns the current plain-text alternative, if any.

Definition at line 159 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

Email::BCC (   $NewValue = NULL)

Get/set message BCC list.

Parameters
array | string$NewValueNew message BCC recipient or array of BCC recipients, in RFC-2822 format ("user@example.com" or "User <user@example.com>" if name included). (OPTIONAL)
Returns
Array of current message BCC recipient(s) in RFC-2822 format.

Definition at line 298 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

Email::Body (   $NewValue = NULL)

Get/set message body.

Parameters
string$NewValueNew message body. (OPTIONAL)
Returns
Current message body.

Definition at line 148 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

Email::CC (   $NewValue = NULL)

Get/set message CC list.

Parameters
array | string$NewValueNew message CC recipient or array of CC recipients, in RFC-2822 format ("user@example.com" or "User <user@example.com>" if name included). (OPTIONAL)
Returns
Array of current message CC recipient(s) in RFC-2822 format.

Definition at line 275 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

Email::CharSet (   $NewValue = NULL)

Specify a character encoding for the message.

This is used to set the PHPMailer::CharSet property.

Parameters
string$NewValueNew character encoding (OPTIONAL)
Returns
Returns the current character encoding.

Definition at line 330 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

static Email::ConvertHtmlToPlainText (   $Html)
static

Try as best as possible to convert HTML to plain text.

Parameters
string$HtmlThe HTML to convert.
Returns
Returns the HTML as plain text.

Definition at line 457 of file Email.php.

static Email::ConvertHtmlWhiteSpace (   $Html,
  $Aggressive = FALSE,
  $LineEnding = "\r\n" 
)
staticprotected

Convert horizontal white space with no semantic value to vertical white space when possible.

Only converts white space between tag attributes by default, but can also convert white space within tags if specified.

Parameters
mixed$HtmlHTML string in which white space should be converted.
bool$AggressiveTRUE to also convert white space within tags in which horizontal whitespace has no semantic value. This should only be used when absolutely necessary because it can make the HTML hard to read. This parameter is optional.
string$LineEndingCharacter sequence to use as the line ending. This parameter is optional.
Returns
Returns the HTML with its horizontal white space converted to vertical white space as specified in the parameters.

Definition at line 902 of file Email.php.

static Email::DefaultFrom (   $NewValue = NULL)
static

Get/set default "From" address.

This address is used when no "From" address is specified for a message.

Parameters
string$NewValueNew default address. (OPTIONAL)
Returns
string Current default address.

Definition at line 213 of file Email.php.

static Email::DeliveryMethod (   $NewValue = NULL)
static

Get/set mail delivery method.

If specified, the method must be one of the predefined "METHOD_" constants.

Parameters
int$NewValueNew delivery method. (OPTIONAL)
Returns
Current delivery method.

Definition at line 489 of file Email.php.

static Email::DeliverySettingErrors ( )
static

Return array with list of delivery setting errors (if any).

Returns
Array with settings that are possibly bad.

Definition at line 668 of file Email.php.

References AlternateBody(), BCC(), Body(), CC(), CharSet(), From(), ReplyTo(), Subject(), and To().

static Email::DeliverySettings (   $NewSettings = NULL)
static

Get/set serialized (opaque text) version of delivery settings.

This method is intended to be used to store and retrieve all email delivery settings for the class, in a form suitable to be saved to a database.

Parameters
array$NewSettingsNew delivery settings values.
Returns
Current delivery settings values.

Definition at line 564 of file Email.php.

static Email::DeliverySettingsOkay ( )
static

Test delivery settings and report their validity.

For example, if the deliver method is set to SMTP it would test the server, port, and (if authentication is indicated) user name and password. If delivery settings are not okay, then DeliverySettingErrors() can be used to determine (if known) which settings may have problems.

Returns
TRUE if delivery settings are okay, otherwise FALSE.

Definition at line 596 of file Email.php.

Email::From (   $NewAddress = NULL,
  $NewName = NULL 
)

Get/set message sender.

Parameters
string$NewAddressNew message sender address. (OPTIONAL, but required if NewName is specified.)
string$NewNameNew message sender name. (OPTIONAL)
Returns
Current message sender in RFC-2822 format ("user@example.com" or "User <user@example.com>" if name available).

Definition at line 189 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

static Email::GetTagInfo (   $Html,
  $TagBegin 
)
staticprotected

Get the tag name and whether it's a closing tag from a tag that begins at a specific offset within some HTML.

This is really only useful to ConvertHtmlWhiteSpace().

Parameters
string$HtmlHTML string from which to get the information.
int$TagBeginOffset of where the tag begins.
Returns
Returns an array containing the tag name and if it's a closing tag.

Definition at line 1014 of file Email.php.

static Email::LineEnding (   $NewValue = NULL)
static

Specify the character sequence that should be used to end lines.

Parameters
string$NewValueCharacter sequence used to end lines.
Returns
Returns the current character sequence used to end lines.

Definition at line 346 of file Email.php.

static Email::Password (   $NewValue = NULL)
static

Get/set password for mail delivery.

Parameters
string$NewValueNew password. (OPTIONAL)
Returns
Current password.

Definition at line 540 of file Email.php.

static Email::Port (   $NewValue = NULL)
static

Get/set port number for mail delivery.

Parameters
int$NewValueNew port number. (OPTIONAL)
Returns
Current port number.

Definition at line 518 of file Email.php.

static Email::RegisterLoggingFunction (   $NewValue)
static

Register a logging callback.

Parameters
callable$NewValueFunction to call just before an Email is sent. The Email will be provided as the first parameter.

Definition at line 121 of file Email.php.

Email::ReplyTo (   $NewAddress = NULL,
  $NewName = NULL 
)

Get/set message "Reply-To" address.

Parameters
string$NewAddressNew message "Reply-To" address. (OPTIONAL, but required if NewName is specified.)
string$NewNameNew message "Reply-To" name. (OPTIONAL)
Returns
Current message "Reply-To" address in RFC-2822 format ("user@example.com" or "User <user@example.com>" if name available).

Definition at line 227 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

Email::Send ( )

Mail the message.

If no recipients have been specified or all recipients were disallowed via whitelisting, successful execution is still reported by returning TRUE.

Returns
TRUE if message was successfully accepted for delivery, otherwise FALSE.

Definition at line 28 of file Email.php.

References StdLib\substr(), and To().

static Email::Server (   $NewValue = NULL)
static

Get/set server for mail delivery.

Parameters
string$NewValueNew server. (OPTIONAL)
Returns
Current server.

Definition at line 507 of file Email.php.

Email::Subject (   $NewValue = NULL)

Get/set message subject.

Parameters
string$NewValueNew message subject. (OPTIONAL)
Returns
Current message subject.

Definition at line 175 of file Email.php.

Referenced by DeliverySettingErrors().

Here is the caller graph for this function:

static Email::TestLineEndings (   $Value,
  $LineEnding 
)
static

Test the line endings in a value to see if they all match the given line ending.

This only works with \r (CR), \n (LF), and \r\n (CRLF).

Parameters
string$ValueString to check.
string$LineEndingLine ending character sequence.
Returns
Returns TRUE if all the line endings match and FALSE otherwise.

Definition at line 424 of file Email.php.

Email::To (   $NewValue = NULL)

Get/set message recipient(s).

Parameters
array | string$NewValueNew message recipient or array of recipients, in RFC-2822 format ("user@example.com" or "User <user@example.com>" if name included). (OPTIONAL)
Returns
Array of current message recipient(s) in RFC-2822 format.

Definition at line 252 of file Email.php.

Referenced by DeliverySettingErrors(), and Send().

Here is the caller graph for this function:

static Email::ToWhitelist (   $NewValue = NULL)
static

Set whitelist of acceptable recipient addresses.

If no whitelist patterns are set, all addresses are acceptable. (Pass in an empty array to clear whitelist.)

Parameters
array$NewValueArray of regular expression patterns to match acceptable email addresses. (OPTIONAL)
Returns
array Array of current whitelist entries.

Definition at line 107 of file Email.php.

static Email::UseAuthentication (   $NewValue = NULL)
static

Get/set whether to use authentication for mail delivery.

Parameters
bool$NewValueNew authentication setting. (OPTIONAL)
Returns
Current authentication setting.

Definition at line 551 of file Email.php.

static Email::UserName (   $NewValue = NULL)
static

Get/set user name for mail delivery.

Parameters
string$NewValueNew user name. (OPTIONAL)
Returns
Current user name.

Definition at line 529 of file Email.php.

static Email::WrapHtmlAsNecessary (   $Html,
  $MaxLineLength = 998,
  $LineEnding = "\r\n" 
)
static

Wrap HTML in an e-mail as necessary to get its lines less than some max length.

This does not guarantee that every line will be less than the max length because it guarantees instead that the sematics of the HTML remain unchanged.

Parameters
string$HtmlHTML to wrap.
int$MaxLineLengthMaximum length of each line. This parameter is optional.
string$LineEndingLine ending character sequence. This parameter is optional.
Returns
Returns HTML that is wrapped as necessary.

Definition at line 368 of file Email.php.

Member Data Documentation

const Email::METHOD_PHPMAIL = 1

Deliver using PHP's internal mail() mechanism.

Definition at line 498 of file Email.php.

const Email::METHOD_SMTP = 2

Deliver using SMTP.

(Requires specifying SMTP settings.)

Definition at line 500 of file Email.php.


The documentation for this class was generated from the following file: