Manual

A Package to enable easy creation of complex multipart emails. If you look for a simple API for creating such emails, then Mail_Mime class will probably suffice. Else you can use Mail_mimePart, which gives you better control about MIME creation.

Mail_Mime::Mail_Mime()

Mail_Mime::Mail_Mime() – creates a new instance

Synopsis

require_once 'Mail/mime.php';

Mail_mime Mail_mime ( mixed $params = array() )

Description

Creates a new instance of Mail_Mime

Parameter

array $params - An associative array of parameters. These parameters affect the way the message is built. Use Mail_Mime::setParam() to set them later.

$params['eol'] - Type of line end. Default is ""\r\n"".
$params['delay_file_io'] - Specifies if attachment files should be read immediately when adding them into message object or when building the message. Useful for big messages handling using saveMessage* functions. Default is "false".
$params['head_encoding'] - Type of encoding to use for the headers of the email. Default is "quoted-printable".
$params['text_encoding'] - Type of encoding to use for the plain text part of the email. Default is "quoted-printable".
$params['html_encoding'] - Type of encoding for the HTML part of the email. Default is "quoted-printable".
$params['head_charset'] - The character set to use for the headers. Default is "iso-8859-1".
$params['text_charset'] - The character set to use for the plain text part of the email. Default is "iso-8859-1".
$params['html_charset'] - The character set to use for the HTML part of the email. Default is "iso-8859-1".

Note

Normally, it is not necessary to set parameters. But, if you want to send the generated MIME message using Mail then you have to set eol to "\n".

For backward compatybility setting end of line string as constructor's first parameter is supported.

If you're working with big attachments, enabling 'delay_file_io' will provent from loading attachments into memory. Until you're not using getMessage* functions don't worry about PHP's memory limit.

Mail_Mime::addAttachment()

Mail_Mime::addAttachment() – add attachment

Synopsis

require_once 'Mail/mime.php';

boolean addAttachment ( string $file , string $c_type = 'application/octet-stream' , string $name = '' , boolean $isfile = true , string $encoding = 'base64' , string $disposition = 'attachment' , string $charset = '' , string $language = '' , string $location = '' , string $n_encoding = null , string $f_encoding = null , string $description = '' , string $h_charset = null )

Description

Adds an attachment to a message.

Parameter

string $file - The file name or the data itself
string $c_type - The content type of the image or file.
string $name - The suggested file name for the data. Only used, if $file contains data.
boolean $isfile - Whether $file is a file name or not.
string $encoding - Type of transfer encoding to use for the file data. Defaults is "base64". For text based files (eg. scripts/html etc.) this could be given as "quoted-printable".
string $disposition - The content-disposition of this file Defaults to attachment. Possible values: attachment, inline.
string $charset - The character set of attachment's content.
string $language - The language of the attachment
string $location - The RFC 2557.4 location of the attachment
string $n_encoding - Encoding of the attachment's name in Content-Type By default filenames are encoded using RFC2231 method Here you can set RFC2047 encoding (quoted-printable or base64) instead.
string $f_encoding - Encoding of the attachment's filename in Content-Disposition header.
string $description - Content-Description header.
string $h_charset - The character set of the headers e.g. filename If not specified, $charset will be used

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"File is not readable `file_name`"	The file was not found or the script has not enough rights to access the file.	Check the file name and path. Check user and file permissions.
NULL	"Could not open `file_name`"	The file is already opened and exclusivly locked by another application.	In the most cases a program opens the file for writing. addAttachment() does no file locking, so this problem is not caused by competitive callings of this function.

Note

This function can not be called statically.

Mail_Mime::addHTMLImage()

Mail_Mime::addHTMLImage() – add image to message

Synopsis

require_once 'Mail/mime.php';

boolean addHTMLImage ( string $file , string $c_type = 'application/octet-stream' , string $name = '' , boolean $isfile = true , string $content_id = null )

Description

If sending an HTML message with embedded images, use this function to add the image.

Parameter

string $file - The image file name or the image data itself
string $c_type - The content type of the image or file.
string $name - The filename of the image. Only used, if $file contains the image data.
boolean $isfile - Whether $file is a filename or not.
string $content_id - The Content-ID value to use for the embedded image. A NULL value will generate a suitably unique Content-ID. When referencing the embedded image with an <img> tag, set the "src" attribute to be "cid:whatever", where "whatever" is the Content-ID.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"File is not readable `file_name`"	The file was not found or the script has not enough rights to access the file.	Check the file name and path. Check user and file permissions.
NULL	"Could not open `file_name`"	The file is already opened and exclusivly locked by another application.	In the most cases a programm opens the file for writing. addHTMLImage() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setHTMLBody()

Mail_Mime::get()

Mail_Mime::get() – build the message

Synopsis

require_once 'Mail/mime.php';

string &get ( array $param = null , resource $filename = null , boolean $skip_head = false )

Description

This function should be called once you have added the text/html/images/attachments. It builds the message and returns it. It does not send it. To send what this function returns (in conjunction with the headers() -function) you would need to use the Mail::send()-function

Parameter

array $param - An associative array of build parameters. See constructor parameters list.
resource $filename - Optional output file where to save the message instead of returning it.
boolean $skip_head - True if you want to return/save only the message without headers.

Return value

string - the body of the message

Note

This function can not be called statically.

For versions older than 1.6.0 Mail_Mime::get() has to be called before Mail_Mime::headers().

See

Mail_Mime::headers()

Mail_Mime::headers()

Mail_Mime::headers() – build the header lines

Synopsis

require_once 'Mail/mime.php';

array &headers ( array $xtra_headers = null , boolean $overwrite = false , boolean $skip_content = false )

Description

Returns an array with the headers needed to prepend to the email (MIME-Version and Content-Type). Please note that the function get() has to be called before calling headers().

Parameter

array $xtra_headers - Additional headers, the format of the argument is $array["header-name"] = "header-value"
boolean $overwrite - Overwrite already existing headers. When FALSE, the values already set are kept.
boolean $skip_content Don't return content headers: Content-Type, Content-Disposition and Content-Transfer-Encoding.

Return value

array - an associative array with the mime headers and the additional headers. The return value can directly passed to the second parameter of Mail::send().

Note

This function can not be called statically.

Mail_Mime::headers() has to be called after Mail_Mime::get().

See

Mail_Mime::get()

Mail_Mime::setHTMLBody()

Mail_Mime::setHTMLBody() – set HTML part

Synopsis

require_once 'Mail/mime.php';

boolean setHTMLBody ( string $data , boolean $isfile = false )

Description

Sets the HTML part of a message

Parameter

string $data - The text to set or, if $isfile is TRUE a valid filename. An URL as argument is not allowed.
boolean $isfile - If TRUE, the content of given file $data is used as message text.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"File is not readable `file_name`"	The file was not found or the script has not enough rights to access the file.	Check the file name and path. Check user and file permissions.
NULL	"Could not open `file_name`"	The file is already opened and exclusivly locked by another application.	In the most cases a programm opens the file for writing. setHTMLBody() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setTxtBody()

Mail_Mime::setTxtBody()

Mail_Mime::setTxtBody() – set plain text part

Synopsis

require_once 'Mail/mime.php';

boolean setTxtBody ( string $data , boolean $isfile = false )

Description

Sets the plain text part of a message

Parameter

string $data - The text to set or, if $isfile is TRUE a valid filename. An URL as argument is not allowed.
boolean $isfile - If TRUE, the content of given file $data is used as message text.

Return value

boolean - Returns TRUE on success, PEAR_Error on failure.

Throws

Possible PEAR_Error values
Error code	Error message	Reason	Solution
NULL	"File is not readable `file_name`"	The file was not found or the script has not enough rights to access the file.	Check the file name and path. Check user and file permissions.
NULL	"Could not open `file_name`"	The file is already opened and exclusivly locked by another application.	In the most cases a programm opens the file for writing. setTxtBody() does no file locking, so this problem is not caused by competitve callings of this function.

Note

This function can not be called statically.

See

Mail_Mime::setHTMLBody()

Mail_Mime::encodeHeader()

Mail_Mime::encodeHeader() – encode header value

Synopsis

require_once 'Mail/mime.php';

string encodeHeader ( string $name , string $value , string $charset , string $encoding )

Description

Returns encoded header value as for RFC2047.

Parameter

string $name - The header name
string $value - The header body
string $charset - Character set used in header body
string $encoding - Encoding ("base64" or "quoted-printable")

Return value

string - Returns encoded header body (without a name)

Note

This function can not be called statically.

Mail_mimePart::Mail_mimePart()

Mail_mimePart::Mail_mimePart() – constructor

Synopsis

require_once 'Mail/mimePart.php';

Mail_mimePart Mail_mimePart ( string $body = '' , array $params = array() )

Description

Create a new Mail_mimePart object.

Parameter

string $body - The body of the mime part if any. Default is an empty string.
array $params - An associative array of parameters:
- $params["content_type"] - The content type for this part ie. multipart/mixed
- $params["encoding"] - The encoding to use ie. 7bit, 8bit, base64 or quoted-printable
- $params["cid"] - content ID to apply
- $params["disposition"] - Content disposition inline or attachment
- $params["filename"] - Optional filename parameter for content disposition
- $params["description"] - Content description
- $params["charset"] - Character set to use
- $params["name_encoding"] - Encoding of the attachment name (Content-Type) By default filenames are encoded using RFC2231 Here you can set RFC2047 encoding (quoted-printable or base64) instead
- $params["filename_encoding"] - Encoding of the attachment filename (Content-Disposition)
- $params["headers_charset"] - Charset of the headers e.g. filename, description If not set, "charset" will be used
- $params["eol"] - End of line sequence. Default: "\r\n"
- $params["body_file"] - Location of file with part's body (instead of $body)
Default is an empty array.

Note

This function can be called statically.

Mail_mimePart::addsubpart()

Mail_mimePart::addsubpart() – add sub part to a MIME part

Synopsis

require_once 'Mail/mimePart.php';

resource &addSubPart ( string $body , array $params )

Description

Adds a sub part to the current MIME part and returns a reference to it

Parameter

string - the body of the sub part
array - the parameter for the sub part. See constructor for the possible values.

Return value

resource - a reference to the added part

Note

This function can not be called statically.

Example

Add two attachments to a mail

<?php    
include 'Mail/mimePart.php';

...

$params['content_type'] = 'multipart/mixed';
$email = new Mail_mimePart('', $params);

// Here we add a text part to the multipart we have
// already. Assume $body contains plain text.

$params['content_type'] = 'text/plain';
$params['encoding']     = '7bit';
$text = $email->addSubPart($body, $params);

// Now add an attachment. Assume $contents is
// the contents of the attachment

$params['content_type'] = 'application/zip';
$params['encoding']     = 'base64';
$params['disposition']  = 'attachment';
$params['dfilename']    = 'example.zip';
$attach =& $email->addSubPart($contents, $params);

// Now build the email. Note that the encode
// function returns an associative array containing two
// elements, body and headers. You will need to add extra
// headers, (eg. Mime-Version) before sending.

$email = $email->encode();
$email['headers']['Mime-Version'] = '1.0';

...
?>

Mail_mimePart::encode()

Mail_mimePart::encode() – encode a mail

Synopsis

require_once 'Mail/mimePart.php';

array encode ( string $boundary = null )

Description

Encodes and returns the email

Parameter

string $boundary - Optional pre-defined boundary string

Return value

array - an associative array containing two elements, body and headers. The headers element is itself an indexed array.

The key names are

'headers' - an array with the mail headers
'body' - a string with the mail body

Note

This function can not be called statically.

Mail_mimePart::encodeToFile()

Mail_mimePart::encodeToFile() – encode a mail

Synopsis

require_once 'Mail/mimePart.php';

array encodeToFile ( string $filename , string $boundary = null , boolean $skip_head = false )

Description

Encodes and saves the email into file. File must exist. Data will be appended to the file

Parameter

string $filename - Output file location
string $boundary - Optional pre-defined boundary string
boolean $skip_head - True if you don't want to save headers

Return value

array - An associative array containing message headers or PEAR error object

Note

This function can not be called statically.

Mail_Mime - Example

Mail_Mime - Example – generation and sending of a MIME mail

Example

<?php

include 'Mail.php';
include 'Mail/mime.php' ;

$text = 'Text version of email';
$html = '<html><body>HTML version of email</body></html>';
$file = '/home/richard/example.php';
$crlf = "\n";
$hdrs = array(
              'From'    => 'you@yourdomain.com',
              'Subject' => 'Test mime message'
              );

$mime = new Mail_mime(array('eol' => $crlf));

$mime->setTXTBody($text);
$mime->setHTMLBody($html);
$mime->addAttachment($file, 'text/plain');

$body = $mime->get();
$hdrs = $mime->headers($hdrs);

$mail =& Mail::factory('mail');
$mail->send('postmaster@localhost', $hdrs, $body);

?>