This class contains static convenience methods for composing addresses and ensuring correct line-breaks in the mail.
Source for this file: /Mail/src/tools.php
Version: | //autogen// |
REPLY_ALL
= 1
|
Reply to all. |
REPLY_SENDER
= 1
|
Reply to sender. |
public static string |
$mxValidateAddress
Email address to use for validateEmailAddressMx(). Change this if this address cannot be used with your Internet Service Provider. Default value: 'postmaster@ez.no'. |
public static string |
$mxValidateServer
Server to use for validateEmailAddressMx(). Change this if this server cannot be used with your Internet Service Provider. Default value: 'smtp.ez.no'. |
public static string |
composeEmailAddress(
$item
)
Returns ezcMailAddress $item as a RFC822 compliant address string. |
public static string |
composeEmailAddresses(
$items
, [ $foldLength
= null] )
Returns the array $items consisting of ezcMailAddress objects as one RFC822 compliant address string. |
public static string |
generateContentId(
[ $partName
= "part"] )
Returns an unique ID to be used for Content-ID headers. |
public static string |
generateMessageId(
$hostname
)
Returns an unique message ID to be used for a mail message. |
public static void |
guessContentType(
$fileName
, &$contentType
, &$mimeType
, $contentType
, $mimeType
)
Guesses the content and mime type by using the file extension. |
public static string |
lineBreak(
)
Returns one endLine character. |
public static string |
mimeDecode(
$text
, [ $charset
= 'utf-8'] )
Decodes mime encoded fields and tries to recover from errors. |
public static ezcMailAddress |
parseEmailAddress(
$address
, [ $encoding
= "mime"] )
Returns an ezcMailAddress object parsed from the address string $address. |
public static array(ezcMailAddress) |
parseEmailAddresses(
$addresses
, [ $encoding
= "mime"] )
Returns an array of ezcMailAddress objects parsed from the address string $addresses. |
public static string |
replaceContentIdRefs(
$htmlText
, $contentIdArray
)
Replaces HTML embedded "cid:" references with replacements from $contentIdArray. |
public static ezcMail |
replyToMail(
$mail
, $from
, [ $type
= self::REPLY_SENDER] , [ $subjectPrefix
= "Re: "] , [ $mailClass
= "ezcMail"] )
Returns a new mail object that is a reply to the current object. |
public static void |
setLineBreak(
$characters
)
Sets the endLine $character(s) to use when generating mail. |
public static bool |
validateEmailAddress(
$address
, [ $checkMxRecords
= false] )
Returns true if $address is a valid email address, false otherwise. |
protected static bool |
validateEmailAddressMx(
$address
)
Checks if the email address $address is valid based on its MX records. |
Returns ezcMailAddress $item as a RFC822 compliant address string.
Example:
Returns:
John Doe
The name part of $item will be surrounded by quotes if it contains any of these characters: , @ < > : ; ' "
Name | Type | Description |
---|---|---|
$item |
ezcMailAddress |
Returns the array $items consisting of ezcMailAddress objects as one RFC822 compliant address string.
Set foldLength to control how many characters each line can have before a line break is inserted according to the folding rules specified in RFC2822.
Name | Type | Description |
---|---|---|
$items |
array(ezcMailAddress) | |
$foldLength |
int |
Returns an unique ID to be used for Content-ID headers.
The part $partName is default set to "part". Another value can be used to provide, for example, a file name of a part. $partName will be encoded with base64 to be compliant with the RFCs.
The formula used is [base64( $partName )]."@".[time].[counter]
Name | Type | Description |
---|---|---|
$partName |
string |
Returns an unique message ID to be used for a mail message.
The hostname $hostname will be added to the unique ID as required by RFC822. If an e-mail address is provided instead, the hostname is extracted and used.
The formula to generate the message ID is: [time_and_date].[process_id].[counter]
Name | Type | Description |
---|---|---|
$hostname |
string |
Guesses the content and mime type by using the file extension.
The content and mime types are returned through the $contentType and $mimeType arguments. For the moment only for image files.
Name | Type | Description |
---|---|---|
$fileName |
string | |
$contentType |
string | |
$mimeType |
string | |
&$contentType |
||
&$mimeType |
Returns one endLine character.
The default is to use "\n\r" as specified by RFC 2045.
Decodes mime encoded fields and tries to recover from errors.
Decodes the $text encoded as a MIME string to the $charset. In case the strict conversion fails this method tries to workaround the issues by trying to "fix" the original $text before trying to convert it.
Name | Type | Description |
---|---|---|
$text |
string | |
$charset |
string |
Returns an ezcMailAddress object parsed from the address string $address.
You can set the encoding of the name part with the $encoding parameter. If $encoding is omitted or set to "mime" parseEmailAddress will asume that the name part is mime encoded.
This method does not perform validation. It will also accept slightly malformed addresses.
If the mail address given can not be decoded null is returned.
Example:
Name | Type | Description |
---|---|---|
$address |
string | |
$encoding |
string |
Returns an array of ezcMailAddress objects parsed from the address string $addresses.
You can set the encoding of the name parts with the $encoding parameter. If $encoding is omitted or set to "mime" parseEmailAddresses will asume that the name parts are mime encoded.
Example:
Name | Type | Description |
---|---|---|
$addresses |
string | |
$encoding |
string |
Replaces HTML embedded "cid:" references with replacements from $contentIdArray.
The method matches all "cid:" references in the $htmlText and then loops over each match. For each match the found content ID is looked-up as key in the $contentIdArray and the value is then inserted as replacement for the "cid:" reference.
The $contentIdArray can be build by iterating over all parts in the mail, and for each ezcMailFilePart that you find: 1. copy the associated file (fileName property of the ezcMailFilePart object) to your webroot; 2. add an element to the array with the key created from the contentId property from the ezcMailFilePart object. See the tutorial for an example of this.
Name | Type | Description |
---|---|---|
$htmlText |
string | |
$contentIdArray |
array(string=>string) |
Returns a new mail object that is a reply to the current object.
The new mail will have the correct to, cc, bcc and reference headers set. It will not have any body set.
By default the reply will only be sent to the sender of the original mail. If $type is set to REPLY_ALL, all the original recipients will be included in the reply.
Use $subjectPrefix to set the prefix to the subject of the mail. The default is to prefix with 'Re: '.
Name | Type | Description |
---|---|---|
$mail |
ezcMail | |
$from |
ezcMailAddress | |
$type |
int | REPLY_SENDER or REPLY_ALL |
$subjectPrefix |
string | |
$mailClass |
string |
Sets the endLine $character(s) to use when generating mail.
The default is to use "\r\n" as specified by RFC 2045.
Name | Type | Description |
---|---|---|
$characters |
string |
Returns true if $address is a valid email address, false otherwise.
By default it will only validate against the same regular expression used in ext/filter. It follows RFC822 and RFC2822.
If $checkMxRecords is true, then an MX records check will be performed also, by sending a test mail (RCPT TO) to $address using the MX records found for the domain part of $address. MX record checking does not work on Windows due to the lack of getmxrr() and checkdnsrr() PHP functions. The ezcBaseFunctionalityNotSupportedException is thrown in this case.
If checking against MX records, set these values before performing the check, to ensure the MX record checks work properly:
The input email address $address should be trimmed from white spaces and/or quotes around it before calling this function (if needed).
An email address has this form:
The localpart has these rules, and these rules are just an approximation of the rules in RFC2822:
See also the test files (in the "Mail/tests/tools/data" directory) for examples of correct and incorrect email addresses.
Name | Type | Description |
---|---|---|
$address |
string | |
$checkMxRecords |
bool |
Type | Description |
---|---|
ezcBaseFunctionalityNotSupportedException |
if $checkMxRecords is true and getmxrr() or checkdnsrr() functions are missing (e.g. on Windows) |
Checks if the email address $address is valid based on its MX records.
Steps:
MX record checking does not work on Windows due to the lack of getmxrr() and checkdnsrr() PHP functions. The ezcBaseFunctionalityNotSupportedException is thrown in this case.
Name | Type | Description |
---|---|---|
$address |
string |
Type | Description |
---|---|
ezcBaseFunctionalityNotSupportedException |
if getmxrr() or checkdnsrr() functions are missing (e.g. on Windows) |