Zeta Components - high quality PHP components

Zeta Components Manual :: Docs For Class ezcMailComposer

Mail::ezcMailComposer

Class ezcMailComposer

Convenience class for writing mail.

This class allows you to create text and/or HTML mail with attachments. If you need to create more advanced mail use the ezcMail class and build the body from scratch.

ezcMailComposer is used with the following steps:

Create a composer object.
Set the subject and recipients.
Set the plainText and htmlText message parts. You can set only one or both. If you set both, the client will display the htmlText if it supports HTML. Otherwise the client will display plainText.
Add any attachments (addFileAttachment() or addStringAttachment()).
Call the build method.

This example shows how to send an HTML mail with a text fallback and attachments. The HTML message has an inline image.

$mail = new ezcMailComposer();
$mail->from = new ezcMailAddress( 'john@example.com', 'John Doe' );
$mail->addTo( new ezcMailAddress( 'cindy@example.com', 'Cindy Doe' ) );
$mail->subject = "Example of an HTML email with attachments";
$mail->plainText = "Here is the text version of the mail. This is displayed if the client can not understand HTML";
$mail->htmlText = "<html>Here is the HTML version of your mail with an image: <img src='file://path_to_image.jpg' /></html>";
$mail->addFileAttachment( 'path_to_attachment.file' );
$mail->build();
$transport = new ezcMailMtaTransport();
$transport->send( $mail );

By default, if the htmlText property contains an HTML image tag with file:// in href, that file will be included in the created message.

Example:

<img src="file:///home/me/image.jpg" />

This can be a security risk if a user links to another file, for example logs or password files. With the automaticImageInclude option (default value true) from ezcMailComposerOptions, the automatic inclusion of files can be turned off.

Example:

$options = new ezcMailComposerOptions();
$options->automaticImageInclude = false; // default value is true
$mail = new ezcMailComposer( $options );
// ... add To, From, Subject, etc to $mail
$mail->htmlText = "<html>Here is the image: <img src="file:///etc/passwd" /></html>";
// ... send $mail

After running the above code, the sent mail will not contain the file specified in the htmlText property.

The file name in the attachment can be different than the file name on disk, by passing an ezcMailContentDispositionHeader object to the function addFileAttachment(). Example:

$mail = new ezcMailComposer();
$mail->from = new ezcMailAddress( 'john@example.com', 'John Doe' );
$mail->addTo( new ezcMailAddress( 'cindy@example.com', 'Cindy Doe' ) );
$mail->subject = "Example of an HTML email with attachments and custom attachment file name";
$mail->plainText = "Here is the text version of the mail. This is displayed if the client can not understand HTML";
$mail->htmlText = "<html>Here is the HTML version of your mail with an image: <img src='file://path_to_image.jpg' /></html>";
$disposition = new ezcMailContentDispositionHeader();
$disposition->fileName = 'custom name for attachment.txt';
$disposition->fileNameCharSet = 'utf-8'; // if using non-ascii characters in the file name
$disposition->disposition = 'attachment'; // default value is 'inline'
$mail->addFileAttachment( 'path_to_attachment.file', null, null, $disposition );
$mail->build();
$transport = new ezcMailMtaTransport();
$transport->send( $mail );

Use the function addStringAttachment() if you want to add an attachment which is stored in a string variable. A file name for a string attachment needs to be specified as well. Example:

$contents = 'contents for mail attachment'; // can be a binary string, eg. image file contents
$mail->addStringAttachment( 'filename', $contents );

Source for this file: /Mail/src/composer.php

ezcMailPart
   |
   --ezcMail
      |
      --ezcMailComposer

Version:

//autogen//

Inherited Constants

From ezcMail:
`ezcMail::BASE64`	Base 64 encoding.
`ezcMail::BINARY`	Binary encoding.
`ezcMail::EIGHT_BIT`	8 bit encoding.
`ezcMail::QUOTED_PRINTABLE`	Quoted printable encoding.
`ezcMail::SEVEN_BIT`	7 bit encoding.

Properties

string	read/write	`$charset` Contains the character set for both $plainText and $htmlText. Default value is 'us-ascii'. This does not set any specific charset for the subject, you need the subjectCharset property for that.
string	read/write	`$encoding` Contains the encoding for both $plainText and $htmlText. Default value is ezcMail::EIGHT_BIT. Other values are found as constants in the class ezcMail.
string	read/write	`$htmlText` Contains the message of the mail in HTML. You should also provide the text of the HTML message in the plainText property. Both will be sent and the receiver will see the HTML message if his/her client supports HTML. If the HTML message contains links to local images and/or files these will be included into the mail when generateBody is called. Links to local files must start with "file://" in order to be recognized. You can use the option automaticImageInclude (default value is true) from ezcMailComposerOptions to turn off the automatic inclusion of files in the generated mail.
ezcMailComposerOptions	read/write	`$options` Options for composing mail. See ezcMailComposerOptions.
string	read/write	`$plainText` Contains the message of the mail in plain text.

Member Variables

protected ezcMailComposerOptions


              $options

Holds the options for this class.

Inherited Member Variables

From ezcMailPart
protected	`ezcMailPart::$properties`

Method Summary

public ezcMailComposer	`__construct( [ $options = null] )` Constructs an empty ezcMailComposer object.
public void	`addAttachment( $fileName , [ $content = null] , [ $contentType = null] , [ $mimeType = null] , [ $contentDisposition = null] )` Adds the file $fileName to the list of attachments.
public void	`addFileAttachment( $fileName , [ $contentType = null] , [ $mimeType = null] , [ $contentDisposition = null] )` Adds the file $fileName to the list of attachments.
public void	`addStringAttachment( $fileName , $content , [ $contentType = null] , [ $mimeType = null] , [ $contentDisposition = null] )` Adds the file $fileName to the list of attachments, with contents $content.
public void	`build( )` Builds the complete email message in RFC822 format.

Inherited Methods

From ezcMail
public ezcMail	`ezcMail::__construct()` Constructs an empty ezcMail object.
public void	`ezcMail::addBcc()` Adds the ezcMailAddress $address to the list of 'bcc' recipients.
public void	`ezcMail::addCc()` Adds the ezcMailAddress $address to the list of 'cc' recipients.
public void	`ezcMail::addTo()` Adds the ezcMailAddress $address to the list of 'to' recipients.
protected static void	`ezcMail::collectPart()` Saves $mail in the $context object.
public array(ezcMailPart)	`ezcMail::fetchParts()` Returns an array of mail parts from the current mail.
public string	`ezcMail::generateBody()` Returns the generated body part of this mail.
public string	`ezcMail::generateHeaders()` Returns the generated headers for the mail.
public void	`ezcMail::walkParts()` Walks recursively through the mail parts in the specified mail object.
From ezcMailPart
public ezcMailPart	`ezcMailPart::__construct()` Constructs a new mail part.
public void	`ezcMailPart::appendExcludeHeaders()` The array $headers will be excluded when the headers are generated.
public string	`ezcMailPart::generate()` Returns the complete mail part including both the header and the body as a string.
public abstract string	`ezcMailPart::generateBody()` Returns the body of this part as a string.
public string	`ezcMailPart::generateHeaders()` Returns the headers set for this part as a RFC 822 string.
public mixed	`ezcMailPart::getHeader()` Returns the RAW value of the header $name.
protected string	`ezcMailPart::getHeaderCharset()` Returns the charset registered for the header $name.
public void	`ezcMailPart::setHeader()` Sets the header $name to the value $value and its charset to $charset.
protected void	`ezcMailPart::setHeaderCharset()` Sets the charset of the header $name to $value.
public void	`ezcMailPart::setHeaders()` Adds the headers $headers.

Methods

__construct

ezcMailComposer __construct( [ezcMailComposerOptions $options = null] )

Constructs an empty ezcMailComposer object.

Parameters:

Name	Type	Description
`$options`	ezcMailComposerOptions

Redefinition of:

Method	Description
`ezcMail::__construct()`	Constructs an empty ezcMail object.

addAttachment

void addAttachment( string $fileName , [string $content = null] , [string $contentType = null] , [string $mimeType = null] , [ezcMailContentDispositionHeader $contentDisposition = null] )

Adds the file $fileName to the list of attachments.

If $content is specified, $fileName is not checked if it exists. $this->attachments will also contain in this case the $content, $contentType and $mimeType.

The $contentType (default = application) and $mimeType (default = octet-stream) control the complete mime-type of the attachment.

If $contentDisposition is specified, the attached file will have its Content-Disposition header set according to the $contentDisposition object and the filename of the attachment in the generated mail will be the one from the $contentDisposition object.

Parameters:

Name	Type	Description
`$fileName`	string
`$content`	string
`$contentType`	string
`$mimeType`	string
`$contentDisposition`	ezcMailContentDispositionHeader

Exceptions:

Type	Description
`ezcBaseFilePermissionProblem`	if $fileName could not be read.
`ezcBaseFileNotFoundException`	if $fileName does not exists.

addFileAttachment

void addFileAttachment( string $fileName , [string $contentType = null] , [string $mimeType = null] , [ezcMailContentDispositionHeader $contentDisposition = null] )

Adds the file $fileName to the list of attachments.

The $contentType (default = application) and $mimeType (default = octet-stream) control the complete mime-type of the attachment.

Parameters:

Name	Type	Description
`$fileName`	string
`$contentType`	string
`$mimeType`	string
`$contentDisposition`	ezcMailContentDispositionHeader

Exceptions:

Type	Description
`ezcBaseFilePermissionProblem`	if $fileName could not be read.
`ezcBaseFileNotFoundException`	if $fileName does not exists.

addStringAttachment

void addStringAttachment( string $fileName , string $content , [string $contentType = null] , [string $mimeType = null] , [ezcMailContentDispositionHeader $contentDisposition = null] )

Adds the file $fileName to the list of attachments, with contents $content.

The file $fileName is not checked if it exists. An attachment is added to the mail, with the name $fileName, and the contents $content.

The $contentType (default = application) and $mimeType (default = octet-stream) control the complete mime-type of the attachment.

Parameters:

Name	Type	Description
`$fileName`	string
`$content`	string
`$contentType`	string
`$mimeType`	string
`$contentDisposition`	ezcMailContentDispositionHeader

build

void build( )

Builds the complete email message in RFC822 format.

This method must be called before the message is sent.

Exceptions:

Type	Description
`ezcBaseFileNotFoundException`	if any of the attachment files can not be found.

Documentation generated by phpDocumentor 1.4.3