fEmailclassv1.0.0b21

Allows creating and sending a single email containing plaintext, HTML, attachments and S/MIME encryption

Please note that this class uses the mail() function by default. Developers that are sending multiple emails, or need SMTP support, should use fSMTP with this class.

This class is implemented to use the UTF-8 character encoding. Please see http://flourishlib.com/docs/UTF-8 for more information.

Changes:
1.0.0b21Added a check to prevent permissions warnings when getting the FQDN on Windows machines 9/2/10
1.0.0b20Fixed send() to only remove the name of a recipient when dealing with the mail() function on Windows and to leave it when using fSMTP 6/22/10
1.0.0b19Changed send() to return the message id for the email, fixed the email regexes to require [] around IPs 5/5/10
1.0.0b18Fixed the name of the static method unindentExpand() 4/28/10
1.0.0b17Added the static method unindentExpand() 4/26/10
1.0.0b16Added support for sending emails via fSMTP 4/20/10
1.0.0b15Added the $unindent_expand_constants parameter to setBody(), added loadBody() and loadHTMLBody(), fixed HTML emails with attachments 3/14/10
1.0.0b14Changed send() to not double .s at the beginning of lines on Windows since it seemed to break things rather than fix them 3/5/10
1.0.0b13Fixed the class to work when safe mode is turned on 10/23/09
1.0.0b12Removed duplicate MIME-Version headers that were being included in S/MIME encrypted emails 10/5/09
1.0.0b11Updated to use the new fValidationException API 9/17/09
1.0.0b10Fixed a bug with sending both an HTML and a plaintext body 6/18/09
1.0.0b9Fixed a bug where the MIME headers were not being set for all emails 6/12/09
1.0.0b8Added the method clearRecipients() 5/29/09
1.0.0b7Email names with UTF-8 characters are now properly encoded 5/8/09
1.0.0b6Fixed a bug where <> quoted email addresses in validation messages were not showing 3/27/09
1.0.0b5Updated for new fCore API 2/16/09
1.0.0b4The recipient error message in validate() no longer contains a typo 2/9/09
1.0.0b3Fixed a bug with missing content in the fValidationException thrown by validate() 1/14/09
1.0.0b2Fixed a few bugs with sending S/MIME encrypted/signed emails 1/10/09
1.0.0bThe initial implementation 6/23/08

Constants

::EMAIL_REGEX

A regular expression to match an email address, exluding those with comments and folding whitespace

The matches will be:

  • [0]: The whole email address
  • [1]: The name before the @
  • [2]: The domain/ip after the @

::NAME_EMAIL_REGEX

A regular expression to match a name <email> string, exluding those with comments and folding whitespace

The matches will be:

  • [0]: The whole name and email address
  • [1]: The name
  • [2]: The whole email address
  • [3]: The email username before the @
  • [4]: The email domain/ip after the @

Static Methods

::compose() protected

Composes text using fText if loaded

Signatures

string compose( string $message, mixed $component )

string compose( mixed .. )

Parameters

string $message The message to compose
mixed $component A string or number to insert into the message
mixed .. ...

Returns

The composed and possible translated message

::fixQmail() public

Sets the class to try and fix broken qmail implementations that add \r to \r\n

Before trying to fix qmail with this method, please try using fSMTP to connect to localhost and pass the fSMTP object to send().

Signature

void fixQmail( )

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration of the class

Signature

void reset( )

::stringlike() protected

Returns TRUE for non-empty strings, numbers, objects, empty numbers and string-like numbers (such as 0, 0.0, '0')

Signature

boolean stringlike( mixed $value )

Parameters

mixed $value The value to check

Returns

If the value is string-like

::unindentExpand() public

Takes a block of text, unindents it and replaces {CONSTANT} tokens with the constant's value

Signature

string unindentExpand( string $text )

Parameters

string $text The text to unindent and replace constants in

Returns

The unindented text

Methods

->__construct() public

Initializes fEmail for creating message ids

Signature

fEmail __construct( )

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string $method The method to create a callback for

Returns

The callback for the method requested

->addAttachment() public

Adds an attachment to the email

If a duplicate filename is detected, it will be changed to be unique.

Signature

void addAttachment( string $filename, string $mime_type, string $contents )

Parameters

string $filename The name of the file to attach
string $mime_type The mime type of the file
string $contents The contents of the file

->addBCCRecipient() public

Adds a blind carbon copy (BCC) email recipient

Signature

void addBCCRecipient( string $email, string $name=NULL )

Parameters

string $email The email address to BCC
string $name The recipient's name

->addCCRecipient() public

Adds a carbon copy (CC) email recipient

Signature

void addCCRecipient( string $email, string $name=NULL )

Parameters

string $email The email address to BCC
string $name The recipient's name

->addRecipient() public

Adds an email recipient

Signature

void addRecipient( string $email, string $name=NULL )

Parameters

string $email The email address to send to
string $name The recipient's name

->clearRecipients() public

Removes all To, CC and BCC recipients from the email

Signature

void clearRecipients( )

->encrypt() public

Sets the email to be encrypted with S/MIME

Signature

void encrypt( string $recipients_smime_cert_file )

Parameters

string $recipients_smime_cert_file The file path to the PEM-encoded S/MIME certificate for the recipient

->loadBody() public

Loads the plaintext version of the email body from a file and applies replacements

The should contain either ASCII or UTF-8 encoded text. Please see http://flourishlib.com/docs/UTF-8 for more information.

Signature

void loadBody( string|fFile $file, array $replacements=array() )

Parameters

string|fFile $file The plaintext version of the email body
array $replacements The method will search the contents of the file for each key and replace it with the corresponding value

Throws

fValidationException
When no file was specified, the file does not exist or the path specified is not a file

->loadHTMLBody() public

Loads the plaintext version of the email body from a file and applies replacements

The should contain either ASCII or UTF-8 encoded text. Please see http://flourishlib.com/docs/UTF-8 for more information.

Signature

void loadHTMLBody( string|fFile $file, array $replacements=array() )

Parameters

string|fFile $file The plaintext version of the email body
array $replacements The method will search the contents of the file for each key and replace it with the corresponding value

Throws

fValidationException
When no file was specified, the file does not exist or the path specified is not a file

->send() public

Sends the email

The return value is the message id, which should be included as the Message-ID header of the email. While almost all SMTP servers will not modify this value, testing has indicated at least one (smtp.live.com for Windows Live Mail) does.

Signature

string send( fSMTP $connection=NULL )

Parameters

fSMTP $connection The SMTP connection to send the message over

Returns

The message id for the message - see method description for details

Throws

fValidationException
When validate() throws an exception

->setBody() public

Sets the plaintext version of the email body

This method accepts either ASCII or UTF-8 encoded text. Please see http://flourishlib.com/docs/UTF-8 for more information.

Signature

void setBody( string $plaintext, boolean $unindent_expand_constants=FALSE )

Parameters

string $plaintext The plaintext version of the email body
boolean $unindent_expand_constants If this is TRUE, the body will be unindented as much as possible and {CONSTANT_NAME} will be replaced with the value of the constant

->setBounceToEmail() public

Adds the email address the email will be bounced to

This email address will be set to the Return-Path header.

Signature

void setBounceToEmail( string $email )

Parameters

string $email The email address to bounce to

->setFromEmail() public

Adds the From: email address to the email

Signature

void setFromEmail( string $email, string $name=NULL )

Parameters

string $email The email address being sent from
string $name The from email user's name - unfortunately on windows this is ignored

->setHTMLBody() public

Sets the HTML version of the email body

This method accepts either ASCII or UTF-8 encoded text. Please see http://flourishlib.com/docs/UTF-8 for more information.

Signature

void setHTMLBody( string $html )

Parameters

string $html The HTML version of the email body

->setReplyToEmail() public

Adds the Reply-To: email address to the email

Signature

void setReplyToEmail( string $email, string $name=NULL )

Parameters

string $email The email address to reply to
string $name The reply-to email user's name

->setSenderEmail() public

Adds the Sender: email address to the email

The Sender: header is used to indicate someone other than the From: address is actually submitting the message to the network.

Signature

void setSenderEmail( string $email, string $name=NULL )

Parameters

string $email The email address the message is actually being sent from
string $name The sender email user's name

->setSubject() public

Sets the subject of the email

This method accepts either ASCII or UTF-8 encoded text. Please see http://flourishlib.com/docs/UTF-8 for more information.

Signature

void setSubject( string $subject )

Parameters

string $subject The subject of the email

->sign() public

Sets the email to be signed with S/MIME

Signature

void sign( string $senders_smime_cert_file, string $senders_smime_pk_file, string $senders_smime_pk_password )

Parameters

string $senders_smime_cert_file The file path to the sender's PEM-encoded S/MIME certificate
string $senders_smime_pk_file The file path to the sender's S/MIME private key
string $senders_smime_pk_password The password for the sender's S/MIME private key