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.
| 1.0.0b21 | Added a check to prevent permissions warnings when getting the FQDN on Windows machines 9/2/10 |
|---|---|
| 1.0.0b20 | Fixed 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.0b19 | Changed send() to return the message id for the email, fixed the email regexes to require [] around IPs 5/5/10 |
| 1.0.0b18 | Fixed the name of the static method unindentExpand() 4/28/10 |
| 1.0.0b17 | Added the static method unindentExpand() 4/26/10 |
| 1.0.0b16 | Added support for sending emails via fSMTP 4/20/10 |
| 1.0.0b15 | Added the $unindent_expand_constants parameter to setBody(), added loadBody() and loadHTMLBody(), fixed HTML emails with attachments 3/14/10 |
| 1.0.0b14 | Changed 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.0b13 | Fixed the class to work when safe mode is turned on 10/23/09 |
| 1.0.0b12 | Removed duplicate MIME-Version headers that were being included in S/MIME encrypted emails 10/5/09 |
| 1.0.0b11 | Updated to use the new fValidationException API 9/17/09 |
| 1.0.0b10 | Fixed a bug with sending both an HTML and a plaintext body 6/18/09 |
| 1.0.0b9 | Fixed a bug where the MIME headers were not being set for all emails 6/12/09 |
| 1.0.0b8 | Added the method clearRecipients() 5/29/09 |
| 1.0.0b7 | Email names with UTF-8 characters are now properly encoded 5/8/09 |
| 1.0.0b6 | Fixed a bug where <> quoted email addresses in validation messages were not showing 3/27/09 |
| 1.0.0b5 | Updated for new fCore API 2/16/09 |
| 1.0.0b4 | The recipient error message in validate() no longer contains a typo 2/9/09 |
| 1.0.0b3 | Fixed a bug with missing content in the fValidationException thrown by validate() 1/14/09 |
| 1.0.0b2 | Fixed a few bugs with sending S/MIME encrypted/signed emails 1/10/09 |
| 1.0.0b | The 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
->__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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 |
