Path

ez components / documentation / api reference / 2009.1rc1 / mail


eZ Components 2009.1rc1

Mail: ezcMailTools

[ Tutorial ] [ Display example ] [ Mail listing example ] [ Rfcs ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcMailTools

This class contains static convenience methods for composing addresses and ensuring correct line-breaks in the mail. [source]

Constants

REPLY_ALL = 1 Reply to all.
REPLY_SENDER = 1 Reply to sender.

Member Variables

public string $mxValidateAddress = 'postmaster@ez.no'
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 string $mxValidateServer = 'smtp.ez.no'
Server to use for validateEmailAddressMx(). Change this if this server cannot be used with your Internet Service Provider.

Default value: 'smtp.ez.no'.

Method Summary

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.

Methods

composeEmailAddress

string composeEmailAddress( ezcMailAddress $item )
Returns ezcMailAddress $item as a RFC822 compliant address string.
Example:
1.  composeEmailAddressnew ezcMailAddress'sender@example.com''John Doe' ) );
Returns:
 John Doe 
The name part of $item will be surrounded by quotes if it contains any of these characters: , @ < > : ; ' "

Parameters

Name Type Description
$item ezcMailAddress  

composeEmailAddresses

string composeEmailAddresses( $items, [int $foldLength = null] )
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.

Parameters

Name Type Description
$items array(ezcMailAddress)  
$foldLength int  

generateContentId

string generateContentId( [string $partName = "part"] )
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]

Parameters

Name Type Description
$partName string  

generateMessageId

string generateMessageId( string $hostname )
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]

Parameters

Name Type Description
$hostname string  

guessContentType

void guessContentType( string $fileName, &$contentType, &$mimeType, string $contentType, string $mimeType )
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.

Parameters

Name Type Description
$fileName string  
$contentType string  
$mimeType string  
&$contentType  
&$mimeType  

lineBreak

string lineBreak( )
Returns one endLine character.
The default is to use "\n\r" as specified by RFC 2045.

mimeDecode

string mimeDecode( string $text, [string $charset = 'utf-8'] )
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.

Parameters

Name Type Description
$text string  
$charset string  

parseEmailAddress

ezcMailAddress parseEmailAddress( string $address, [string $encoding = "mime"] )
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:
1.  ezcMailTools::parseEmailAddress'John Doe <john@example.com>' );

Parameters

Name Type Description
$address string  
$encoding string  

parseEmailAddresses

array(ezcMailAddress) parseEmailAddresses( string $addresses, [string $encoding = "mime"] )
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:
1.  ezcMailTools::parseEmailAddresses'John Doe <john@example.com>' );

Parameters

Name Type Description
$addresses string  
$encoding string  

replaceContentIdRefs

string replaceContentIdRefs( string $htmlText, array(string=>string) $contentIdArray )
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.
1.  <?php
2.  $contentIdArray array'consoletools-table.png@1421450' => 'http://localhost/consoletools-table.jpg' );
3.  $text "<html> Embedded image: <img src='cid:consoletools-table.png@1421450'/> </html>";
4.  $htmlBody ezcMailTools::replaceContentIdRefs$text$contentIdArray );
5.  // $htmlBody is now:
6.  // <html> Embedded image: <img src='http://localhost/consoletools-table.jpg'/> </html>
7.   ?>
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.

Parameters

Name Type Description
$htmlText string  
$contentIdArray array(string=>string)  

replyToMail

ezcMail replyToMail( ezcMail $mail, ezcMailAddress $from, [int $type = self::REPLY_SENDER], [string $subjectPrefix = "Re: "], [string $mailClass = "ezcMail"] )
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: '.

Parameters

Name Type Description
$mail ezcMail  
$from ezcMailAddress  
$type int REPLY_SENDER or REPLY_ALL
$subjectPrefix string  
$mailClass string  

setLineBreak

void setLineBreak( string $characters )
Sets the endLine $character(s) to use when generating mail.
The default is to use "\r\n" as specified by RFC 2045.

Parameters

Name Type Description
$characters string  

validateEmailAddress

bool validateEmailAddress( string $address, [bool $checkMxRecords = false] )
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:
1.  ezcMailTools::$mxValidateServer 'your.mail.server'// default 'smtp.ez.no'
1.   ezcMailTools::$mxValidateAddress 'email@mail.server'// default 'postmaster@ez.no'
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:
1.    localpart@domainpart
The localpart has these rules, and these rules are just an approximation of the rules in RFC2822:
  • allowed characters: . + ~ / ' - _ ` ^ $ % & ! ' | {
  • the dot (.) cannot be the first or the last character
  • the double-quote character (") can only surround the localpart (so if it appears it must be the first and the last character of localpart)
  • spaces are allowed if the localpart is surrounded in double-quotes
  • other ASCII characters (even from the extended-ASCII set) are allowed if the localparts is surrounded in double-quotes (the function ezcMailTools::composeEmailAddress will encode it when using it in a mail header)
  • the double-quotes character (") cannot be escaped to appear in a localpart surrounded by double quotes (so "john"doe"@example.com is not a valid email address)
The domainpart has the same rules as a domain name, as defined in RFC822 and RFC2822.
See also the test files (in the "Mail/tests/tools/data" directory) for examples of correct and incorrect email addresses.

Parameters

Name Type Description
$address string  
$checkMxRecords bool  

Throws

ClassDescription
ezcBaseFunctionalityNotSupportedException if $checkMxRecords is true and getmxrr() or checkdnsrr() functions are missing (e.g. on Windows)

validateEmailAddressMx

bool validateEmailAddressMx( string $address )
Checks if the email address $address is valid based on its MX records.
Steps:
  • the MX records are fetched for the domain part of $address, along with their weights
  • the MX records are sorted based on the weights
  • for each MX record a connection is open
  • a test mail (RCPT TO) is tried to be sent to $address
  • if one test mail succeeds, then the address is valid, else invalid
Set these values before calling this function, to ensure the MX record checks work properly:
1.  ezcMailTools::$mxValidateServer 'your.mail.server'// default 'smtp.ez.no'
1.   ezcMailTools::$mxValidateAddress 'email@mail.server'// default 'postmaster@ez.no'
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.

Parameters

Name Type Description
$address string  

Throws

ClassDescription
ezcBaseFunctionalityNotSupportedException if getmxrr() or checkdnsrr() functions are missing (e.g. on Windows)

Last updated: Mon, 22 Jun 2009