Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcMailTools

Mail::ezcMailTools

Class ezcMailTools

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//

Constants

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

Member Variables

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

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

static string composeEmailAddress( ezcMailAddress $item )

Returns ezcMailAddress $item as a RFC822 compliant address string.

Example:

composeEmailAddress( new 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

static 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

static 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

static 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

static 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

static string lineBreak( )

Returns one endLine character.

The default is to use "\n\r" as specified by RFC 2045.

mimeDecode

static 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

static 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:

ezcMailTools::parseEmailAddress( 'John Doe <john@example.com>' );

Parameters:

Name	Type	Description
`$address`	string
`$encoding`	string

parseEmailAddresses

static 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:

ezcMailTools::parseEmailAddresses( 'John Doe <john@example.com>' );

Parameters:

Name	Type	Description
`$addresses`	string
`$encoding`	string

replaceContentIdRefs

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

<?php
$contentIdArray = array( 'consoletools-table.png@1421450' => 'http://localhost/consoletools-table.jpg' );
$text = "<html> Embedded image: <img src='cid:consoletools-table.png@1421450'/> </html>";
$htmlBody = ezcMailTools::replaceContentIdRefs( $text, $contentIdArray );
// $htmlBody is now:
// <html> Embedded image: <img src='http://localhost/consoletools-table.jpg'/> </html>
?>

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

static 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

static 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

static 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:

ezcMailTools::$mxValidateServer = 'your.mail.server'; // default 'smtp.ez.no'
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:

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

Exceptions:

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

validateEmailAddressMx

static 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:

ezcMailTools::$mxValidateServer = 'your.mail.server'; // default 'smtp.ez.no'
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

Exceptions:

Type	Description
`ezcBaseFunctionalityNotSupportedException`	if getmxrr() or checkdnsrr() functions are missing (e.g. on Windows)

Documentation generated by phpDocumentor 1.4.3