Path

ez components / documentation / api reference / 2009.2.1 / mail

eZ Components 2009.2.1

Mail: ezcMailComposer

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

Class: ezcMailComposer

Convenience class for writing mail. [source]
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:
  1. Create a composer object.
  2. Set the subject and recipients.
  3. 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.
  4. Add any attachments (addFileAttachment() or addStringAttachment()).
  5. 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. 
 1.  $mail = new ezcMailComposer();
 2.  $mail->from = new ezcMailAddress( 'john@example.com', 'John Doe' );
 3.  $mail->addTo( new ezcMailAddress( 'cindy@example.com', 'Cindy Doe' ) );
 4.  $mail->subject = "Example of an HTML email with attachments";
 5.  $mail->plainText = "Here is the text version of the mail. This is displayed if the client can not understand HTML";
 6.  $mail->htmlText = "<html>Here is the HTML version of your mail with an image: <img src='file://path_to_image.jpg' /></html>";
 7.  $mail->addFileAttachment( 'path_to_attachment.file' );
 8.  $mail->build();
 9.  $transport = new ezcMailMtaTransport();
10.  $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: 
 1.  <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: 
 1.  $options = new ezcMailComposerOptions();
 2.  $options->automaticImageInclude = false; // default value is true
 3.  
 4.  $mail = new ezcMailComposer( $options );
 5.  
 6.  // ... add To, From, Subject, etc to $mail
 7.  $mail->htmlText = "<html>Here is the image: <img src="file:///etc/passwd" /></html>";
 8.  
 9.  // ... 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: 
 1.  $mail = new ezcMailComposer();
 2.  $mail->from = new ezcMailAddress( 'john@example.com', 'John Doe' );
 3.  $mail->addTo( new ezcMailAddress( 'cindy@example.com', 'Cindy Doe' ) );
 4.  $mail->subject = "Example of an HTML email with attachments and custom attachment file name";
 5.  $mail->plainText = "Here is the text version of the mail. This is displayed if the client can not understand HTML";
 6.  $mail->htmlText = "<html>Here is the HTML version of your mail with an image: <img src='file://path_to_image.jpg' /></html>";
 7.  
 8.  $disposition = new ezcMailContentDispositionHeader();
 9.  $disposition->fileName = 'custom name for attachment.txt';
10.  $disposition->fileNameCharSet = 'utf-8'; // if using non-ascii characters in the file name
11.  $disposition->disposition = 'attachment'; // default value is 'inline'
12.  
13.  $mail->addFileAttachment( 'path_to_attachment.file', null, null, $disposition );
14.  $mail->build();
15.  
16.  $transport = new ezcMailMtaTransport();
17.  $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:
 1.  $contents = 'contents for mail attachment'; // can be a binary string, eg. image file contents
 2.  $mail->addStringAttachment( 'filename', $contents );

Parents

ezcMailPart
   |
   --ezcMail
      |
      --ezcMailComposer

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  

Throws

ClassDescription
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.
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  
$contentType string  
$mimeType string  
$contentDisposition ezcMailContentDispositionHeader  

Throws

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

build

void build( )
Builds the complete email message in RFC822 format.
This method must be called before the message is sent.

Throws

ClassDescription
ezcBaseFileNotFoundException if any of the attachment files can not be found.

Last updated: Tue, 23 Mar 2010