PHP Unframework
PHP Unframework
PHP Unframework
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.0b30 | Changed methods to return instance for method chaining 9/12/11 |
|---|---|
| 1.0.0b29 | Changed combineNameEmail() to be a static method and to be exposed publicly for use by other classes 7/26/11 |
| 1.0.0b28 | Fixed addAttachment() and addRelatedFile() to properly handle duplicate filenames 5/17/11 |
| 1.0.0b27 | Fixed a bug with generating FQDNs on some Windows machines 2/24/11 |
| 1.0.0b26 | Added addCustomerHeader() 2/2/11 |
| 1.0.0b25 | Fixed a bug with finding the FQDN on non-Windows machines 1/19/11 |
| 1.0.0b24 | Backwards Compatibility Break - the $contents parameter of addAttachment() is now first instead of third, addAttachment() will now accept fFile objects for the $contents parameter, added addRelatedFile() 12/1/10 |
| 1.0.0b23 | Fixed a bug on Windows where emails starting with a . would have the . removed 9/11/10 |
| 1.0.0b22 | Revamped the FQDN code and added getFQDN() 9/7/10 |
| 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 |
A regular expression to match an email address, exluding those with comments and folding whitespace
The matches will be:
A regular expression to match a name <email> string, exluding those with comments and folding whitespace
The matches will be:
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
Turns a name and email into a "name" <email> string, or just email if no name is provided
This method will remove newline characters from the name and email, and will remove any backslash (\) and double quote (") characters from the name.
string combineNameEmail( string $name, string $email )
| string | $name | The name associated with the email address |
| string | The email address |
The '"name" <email>' or 'email' string
Composes text using fText if loaded
string compose( string $message, mixed $component [, ... ] )
| string | $message | The message to compose |
| mixed | $component [, ... ] | A string or number to insert into the message |
The composed and possible translated message
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().
void fixQmail( )
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
Returns the fully-qualified domain name of the server
string getFQDN( )
The fully-qualified domain name of the server
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
void reset( )
Returns TRUE for non-empty strings, numbers, objects, empty numbers and string-like numbers (such as 0, 0.0, '0')
boolean stringlike( mixed $value )
| mixed | $value | The value to check |
If the value is string-like
Takes a block of text, unindents it and replaces {CONSTANT} tokens with the constant's value
string unindentExpand( string $text )
| string | $text | The text to unindent and replace constants in |
The unindented text
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
callback __get( string $method )
| string | $method | The method to create a callback for |
The callback for the method requested
Adds an attachment to the email
If a duplicate filename is detected, it will be changed to be unique.
fEmail addAttachment( string|fFile $contents, string $filename=NULL, string $mime_type=NULL )
| string|fFile | $contents | The contents of the file |
| string | $filename | The name to give the attachement - optional if $contents is an fFile object |
| string | $mime_type | The mime type of the file - this allows overriding the mime type of the file if incorrectly detected |
The email object, to allow for method chaining
Adds a blind carbon copy (BCC) email recipient
fEmail addBCCRecipient( string $email, string $name=NULL )
| string | The email address to BCC | |
| string | $name | The recipient's name |
The email object, to allow for method chaining
Adds a carbon copy (CC) email recipient
fEmail addCCRecipient( string $email, string $name=NULL )
| string | The email address to BCC | |
| string | $name | The recipient's name |
The email object, to allow for method chaining
Allows adding a custom header to the email
If the method is called multiple times with the same name, the last value will be used.
Please note that this class will properly format the header, including adding the : between the name and value and wrapping values that are too long for a single line.
fEmail addCustomHeader( string $name, string $value )
fEmail addCustomHeader( array $headers )
| string | $name | The name of the header |
| string | $value | The value of the header |
| array | $headers | An associative array of {name} => {value} |
The email object, to allow for method chaining
Adds an email recipient
fEmail addRecipient( string $email, string $name=NULL )
| string | The email address to send to | |
| string | $name | The recipient's name |
The email object, to allow for method chaining
Adds a “related” file to the email, returning the Content-ID for use in HTML
The purpose of a related file is to be able to reference it in part of the HTML body. Image src URLs can reference a related file by starting the URL with cid: and then inserting the Content-ID.
If a duplicate filename is detected, it will be changed to be unique.
string addRelatedFile( string|fFile $contents, string $filename=NULL, string $mime_type=NULL )
| string|fFile | $contents | The contents of the file |
| string | $filename | The name to give the attachement - optional if $contents is an fFile object |
| string | $mime_type | The mime type of the file - this allows overriding the mime type of the file if incorrectly detected |
The fully-formed cid: URL for use in HTML src attributes
Removes all To, CC and BCC recipients from the email
fEmail clearRecipients( )
The email object, to allow for method chaining
Sets the email to be encrypted with S/MIME
fEmail encrypt( string $recipients_smime_cert_file )
| string | $recipients_smime_cert_file | The file path to the PEM-encoded S/MIME certificate for the recipient |
The email object, to allow for method chaining
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.
fEmail loadBody( string|fFile $file, array $replacements=array() )
| 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 |
The email object, to allow for method chaining
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.
fEmail loadHTMLBody( string|fFile $file, array $replacements=array() )
| 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 |
The email object, to allow for method chaining
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.
string send( fSMTP $connection=NULL )
| fSMTP | $connection | The SMTP connection to send the message over |
The message id for the message - see method description for details
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.
fEmail setBody( string $plaintext, boolean $unindent_expand_constants=FALSE )
| 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 |
The email object, to allow for method chaining
Adds the email address the email will be bounced to
This email address will be set to the Return-Path header.
fEmail setBounceToEmail( string $email )
| string | The email address to bounce to |
The email object, to allow for method chaining
Adds the From: email address to the email
fEmail setFromEmail( string $email, string $name=NULL )
| string | The email address being sent from | |
| string | $name | The from email user's name - unfortunately on windows this is ignored |
The email object, to allow for method chaining
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.
fEmail setHTMLBody( string $html )
| string | $html | The HTML version of the email body |
The email object, to allow for method chaining
Adds the Reply-To: email address to the email
fEmail setReplyToEmail( string $email, string $name=NULL )
| string | The email address to reply to | |
| string | $name | The reply-to email user's name |
The email object, to allow for method chaining
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.
fEmail setSenderEmail( string $email, string $name=NULL )
| string | The email address the message is actually being sent from | |
| string | $name | The sender email user's name |
The email object, to allow for method chaining
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.
fEmail setSubject( string $subject )
| string | $subject | The subject of the email |
The email object, to allow for method chaining
Sets the email to be signed with S/MIME
fEmail sign( string $senders_smime_cert_file, string $senders_smime_pk_file, string $senders_smime_pk_password )
| 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 |
The email object, to allow for method chaining
