Flourish PHP Unframework

fMailbox

Class Resources

Static Methods

Methods

Uses

class, v1.0.0b18

Retrieves and deletes messages from a email account via IMAP or POP3

All headers, text and html content returned by this class are encoded in UTF-8. Please see http://flourishlib.com/docs/UTF-8 for more information.

Changes:
1.0.0b18Fixed a bug in fetchMessageSource() where IMAP connections would add an extra \r\n to the end of the source 9/16/12
1.0.0b17Updated the class to be more forgiving when parsing the response for STATUS and FETCH IMAP commands 9/15/12
1.0.0b16Added method fetchMessageSource() 9/15/12
1.0.0b15Fixed handling of bounces with no headers 9/15/12
1.0.0b14Added a workaround for iconv having issues in MAMP 1.9.4+ 7/26/11
1.0.0b13Fixed handling of headers in relation to encoded-words being embedded inside of quoted strings 7/26/11
1.0.0b12Enhanced the error checking in write() 6/3/11
1.0.0b11Added code to work around PHP bug #42682 (http://bugs.php.net/bug.php?id=42682) where stream_select() doesn't work on 64bit machines from PHP 5.2.0 to 5.2.5, improved connectivity error handling and timeouts while reading data 1/10/11
1.0.0b10Fixed parseMessage() to properly handle a header format edge case and properly set the text and html keys even when the email has an explicit Content-disposition: inline header 11/25/10
1.0.0b9Fixed a bug in parseMessage() that could cause HTML alternate content to be included in the inline content array instead of the html element 9/20/10
1.0.0b8Fixed parseMessage() to be able to handle non-text/non-html multipart parts that do not have a Content-disposition header 9/18/10
1.0.0b7Fixed a typo in read() 9/7/10
1.0.0b6Fixed a typo from 1.0.0b4 7/21/10
1.0.0b5Fixes for increased compatibility with various IMAP and POP3 servers, hacked around a bug in PHP 5.3 on Windows 6/22/10
1.0.0b4Added code to handle emails without an explicit Content-type header 6/4/10
1.0.0b3Added missing static method callback constants 5/11/10
1.0.0b2Added the missing enableDebugging() 5/5/10
1.0.0bThe initial implementation 5/5/10

Static Methods

::addSMIMEPair() public

Adds an S/MIME certificate, or certificate + private key pair for verification and decryption of S/MIME messages

Signature

void addSMIMEPair( string $email_address, fFile|string $certificate_file, fFile $private_key_file=NULL, string $private_key_password=NULL )

Parameters

string $email_address The email address the certificate or private key is for
fFile|string $certificate_file The file the S/MIME certificate is stored in - required for verification and decryption
fFile $private_key_file The file the S/MIME private key is stored in - required for decryption only
string $private_key_password The password for the private key

::parseMessage() public

Parses a MIME message into an associative array of information

The output includes the following keys:

  • 'received': The date the message was received by the server
  • 'headers': An associative array of mail headers, the keys are the header names, in lowercase

And one or more of the following:

  • 'text': The plaintext body
  • 'html': The HTML body
  • 'attachment': An array of attachments, each containing:
    • 'filename': The name of the file
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'inline': An array of inline files, each containing:
    • 'filename': The name of the file
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'related': An associative array of related files, such as embedded images, with the key 'cid:{content-id}' and an array value containing:
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'verified': If the message contents were verified via an S/MIME certificate - if not verified the smime.p7s will be listed as an attachment
  • 'decrypted': If the message contents were decrypted via an S/MIME private key - if not decrypted the smime.p7m will be listed as an attachment

All values in headers, text and body will have been decoded to UTF-8. Files in the attachment, inline and related array will all retain their original encodings.

Signature

array parseMessage( string $message, boolean $convert_newlines=FALSE )

Parameters

string $message The full source of the email message
boolean $convert_newlines If \r\n should be converted to \n in the text and html parts the message

Returns

The parsed email message - see method description for details

::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( )

Methods

->__construct() public

Configures the connection to the server

Please note that the GMail POP3 server does not act like other POP3 servers and the GMail IMAP server should be used instead. GMail POP3 only allows retrieving a message once - during future connections the email in question will no longer be available.

Signature

fMailbox __construct( string $type, string $host, string $username, string $password, integer $port=NULL, boolean $secure=FALSE, integer $timeout=NULL )

Parameters

string $type The type of mailbox, 'pop3' or 'imap'
string $host The server hostname or IP address
string $username The user to log in as
string $password The user's password
integer $port The port to connect via - only required if non-standard
boolean $secure If SSL should be used for the connection - this requires the openssl extension
integer $timeout The timeout to use when connecting

->__destruct() public

Disconnects from the server

Signature

void __destruct( )

->close() public

Closes the connection to the server

Signature

void close( )

->deleteMessages() public

Deletes one or more messages from the server

Passing more than one UID at a time is more efficient for IMAP mailboxes, whereas POP3 mailboxes will see no difference in performance.

Signature

void deleteMessages( integer|array $uid )

Parameters

integer|array $uid The UID(s) of the message(s) to delete

->enableDebugging() public

Sets if debug messages should be shown

Signature

void enableDebugging( boolean $flag )

Parameters

boolean $flag If debugging messages should be shown

->fetchMessage() public

Retrieves a single message from the server

The output includes the following keys:

  • 'uid': The UID of the message
  • 'received': The date the message was received by the server
  • 'headers': An associative array of mail headers, the keys are the header names, in lowercase

And one or more of the following:

  • 'text': The plaintext body
  • 'html': The HTML body
  • 'attachment': An array of attachments, each containing:
    • 'filename': The name of the file
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'inline': An array of inline files, each containing:
    • 'filename': The name of the file
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'related': An associative array of related files, such as embedded images, with the key 'cid:{content-id}' and an array value containing:
    • 'mimetype': The mimetype of the file
    • 'data': The raw contents of the file
  • 'verified': If the message contents were verified via an S/MIME certificate - if not verified the smime.p7s will be listed as an attachment
  • 'decrypted': If the message contents were decrypted via an S/MIME private key - if not decrypted the smime.p7m will be listed as an attachment

All values in headers, text and body will have been decoded to UTF-8. Files in the attachment, inline and related array will all retain their original encodings.

Signature

array fetchMessage( integer $uid, boolean $convert_newlines=FALSE )

Parameters

integer $uid The UID of the message to retrieve
boolean $convert_newlines If \r\n should be converted to \n in the text and html parts the message

Returns

The parsed email message - see method description for details

->fetchMessageSource() public

Retrieves the raw source of a single message from the server

This method is primarily useful for storing the raw source of a message. Normal use of fMailbox would involved calling fetchMessage(), which calls this method and then parseMessage().

Signature

string fetchMessageSource( integer $uid )

Parameters

integer $uid The UID of the message to retrieve

Returns

The raw message source of the email

->listMessages() public

Gets a list of messages from the server

The structure of the returned array is:

array(
    (integer) {uid} => array(
        'uid'         => (integer) {a unique identifier for this message on this server},
        'received'    => (string) {date message was received},
        'size'        => (integer) {size of message in bytes},
        'date'        => (string) {date message was sent},
        'from'        => (string) {the from header value},
        'subject'     => (string) {the message subject},
        'message_id'  => (string) {optional - the message-id header value, should be globally unique},
        'to'          => (string) {optional - the to header value},
        'in_reply_to' => (string) {optional - the in-reply-to header value}
    ), ...
)

All values will have been decoded to UTF-8.

Signature

array listMessages( integer $limit=NULL, integer $page=NULL )

Parameters

integer $limit The number of messages to retrieve
integer $page The page of messages to retrieve

Returns

A list of messages on the server - see method description for details