Create MIME messages.
Summary
- Introduction
- Legal Copyright (C) 2008 Stephane Lavergne http://www.imars.com/
- Description Facilitates the creation of MIME compatible messages.
- Properties
- charset Character set to assume for all text parts attached.
- Overloading To define any header, set a property of the same name.
- Methods
- email Instantiate the email class.
- addData Add a raw data part to message.
- addFile Attach a file to message.
- addText Attach plain text to message.
- addHTML Attach HTML to message.
- addTextHTML Add a pair of text and HTML equivalents to message.
- build Build message to a string.
- send Build and immediately send message.
Introduction
Legal
Copyright (C) 2008 Stephane Lavergne http://www.imars.com/
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Description
Facilitates the creation of MIME compatible messages. It has useful features like easy creation of alternative bodies (i.e. plain+html) and multiple file attachments. It is not a complete implementation, but it is very small (about 5kb without comments) which is a big plus for my needs.
Example
require_once 'email.inc';
mb_internal_encoding('UTF-8');
$msg = new email();
$msg->charset = 'UTF-8';
$msg->to = "Someone <foo@example.com>";
$msg->from = "Myself <bar@example.com>";
$msg->subject = "Friendly reminder service";
$msg->addText("Hello Someone,\n\nThis is your friendly reminder.\n");
$msg->addFile('image/png', '/tmp/test-file.png', 'reminder.png');
$msg->send();
Basically, you instantiate the email class, set a few headers, add some content parts (at least one) and either build to a string using build() or send using PHP's mail() with send().
Properties
charset
var $charset
Character set to assume for all text parts attached. Default: 'UTF-8'. Be sure to explicitly set PHP's mb_internal_encoding() to the same character set as this property, or else headers will not be encoded properly.
Overloading
To define any header, set a property of the same name. If the header name contains dashes, use underscores instead and they will be converted to dashes. For example:
$msg = new email(); $msg->X_Mailer_Info = "My Custom Mailer v0.15";
Methods
function email()
Instantiate the email class.
addData
function addData($type, $displayname, $data)
Add a raw data part to message.
Netiquette
You should add text and HTML parts before binary file attachments.
Parameters
- type
- MIME type of the attachment. (i.e. 'text/plain')
- displayname
- File name to suggest to reader.
- data
- Actual raw data to include.
Returns
No return value.
addFile
function addFile($type, $filepath, $displayname)
Attach a file to message.
Netiquette
You should add text and HTML parts before binary file attachments.
Parameters
- type
- MIME type of the attachment. (i.e. 'image/png')
- filepath
- Path on local file system.
- displayname
- File name to suggest to reader.
Returns
No return value.
addText
function addText($text)
Attach plain text to message.
Parameters
- text
- String of text to attach.
Returns
No return value.
addHTML
function addHTML($html)
Attach HTML to message.
Parameters
- html
- String of HTML to attach.
Returns
No return value.
addTextHTML
function addTextHTML($text, $html)
Add a pair of text and HTML equivalents to message. This implements the “multipart/alternative” type so viewers can expect the text and HTML to represent the same contents.
Parameters
- text
- The plain text string.
- html
- The HTML string.
Returns
No return value.
build
function build($skipTS = false)
Build message to a string.
Caveats
If you intend to use PHP's mail(), you will need to split headers from the body yourself since PHP needs headers separately. Something like this:
// Assuming your email is $msg:
$parts = preg_split('/\r?\n\r?\n/', $msg->build(true), 2);
mail($msg->getTo(), $msg->getSubject(), $parts[1], $parts[0]);
Parameters
- skipTS
- Skip “To:” and “Subject:” header fields. Useful if you intend to use PHP's mail().
Returns
String containing the entire message ready to send (i.e. via sendmail.)
send
function send()
Build and immediately send message. Note that you can modify some headers and call build() or send() again on the current message. This can be handy for mailing lists where only the destination changes (and where using the “Bcc” field isn't appropriate, that is.)
Internally, this uses PHP's popen() to invoke your PHP configuration's “sendmail_path” directly. This avoids the extra overhead and formatting limitations of PHP's built-in mail().
Returns
FALSE if the pipe could not be opened, the termination status of the sendmail process otherwise.