Mail: ezcMailImapTransport
[ ]
[ Display-example ] [ Mail-listing-example ] [ Rfcs ]
[ ]
[ ]
[ ]
[ ]
Class: ezcMailImapTransport
|
ezcMailImapTransport implements IMAP for mail retrieval. [
source]
The implementation supports most of the basic commands specified in http://www.faqs.org/rfcs/rfc1730.html (IMAP4) and http://www.faqs.org/rfcs/rfc2060.html (IMAP4rev1)
Properties
Method Summary
|
public void |
append(
$mailbox, $mail, [$flags = null] )
Appends $mail to the $mailbox mailbox. |
|
public bool |
authenticate(
$user, $password )
Authenticates the user to the IMAP server with $user and $password. |
|
public array(string) |
capability(
)
Returns an array with the capabilities of the IMAP server. |
|
public bool |
clearFlag(
$messages, $flag )
Clears $flag from $messages. |
|
public bool |
copyMessages(
$messages, $destination )
Copies message(s) from the selected mailbox to mailbox $destination. |
|
public int |
countByFlag(
$flag )
Wrapper function to fetch count of messages by a certain flag. |
|
public bool |
createMailbox(
$mailbox )
Creates the mailbox $mailbox. |
|
public bool |
delete(
$msgNum )
Deletes the message with the message number $msgNum from the server. |
|
public bool |
deleteMailbox(
$mailbox )
Deletes the mailbox $mailbox. |
|
public void |
disconnect(
)
Disconnects the transport from the IMAP server. |
|
public void |
expunge(
)
Sends an EXPUNGE command to the server. |
|
public ezcMailParserSet |
fetchAll(
[$deleteFromServer = false] )
Returns a parserset with all the messages on the server. |
|
public ezcMailImapSet |
fetchByFlag(
$flag )
Fetches messages by a certain flag. |
|
public ezcMailImapSet |
fetchByMessageNr(
$number, [$deleteFromServer = false] )
Returns an ezcMailImapSet containing only the $number -th message in the mailbox. |
|
public array(int=>mixed) |
fetchFlags(
$messages )
Fetches IMAP flags for messages $messages. |
|
public ezcMailImapSet |
fetchFromOffset(
$offset, [$count = 0], [$deleteFromServer = false] )
Returns an ezcMailImapSet with $count messages starting from $offset. |
|
public array(int=>string) |
listMailboxes(
[$reference = ''], [$mailbox = '*'] )
Lists the available mailboxes on the IMAP server. |
|
public array(int=>int) |
listMessages(
[$contentType = null] )
Returns a list of the not deleted messages in the current mailbox. |
|
public array(int=>string) |
listUniqueIdentifiers(
[$msgNum = null] )
Returns the unique identifiers messages on the IMAP server. |
|
public void |
noop(
)
Sends a NOOP command to the server, use it to keep the connection alive. |
|
public bool |
renameMailbox(
$mailbox, $newName )
Renames the mailbox $mailbox to $newName. |
|
public ezcMailImapTransport |
__construct(
$server, [$port = null], [$options = array()] )
Creates a new IMAP transport and connects to the $server at $port. |
|
public void |
__destruct(
)
Destructs the IMAP transport. |
|
public void |
selectMailbox(
$mailbox, [$readOnly = false] )
Selects the mailbox $mailbox. |
|
public bool |
setFlag(
$messages, $flag )
Sets $flag on $messages. |
|
public ezcMailImapSet |
sortFromOffset(
$offset, [$count = 0], $sortCriteria, [$reverse = false] )
Fetches $count messages from $offset sorted by $sortCriteria. |
|
public ezcMailImapSet |
sortMessages(
$messages, $sortCriteria, [$reverse = false] )
Fetches messages $messages sorted by $sortCriteria. |
|
public bool |
status(
&$numMessages, &$sizeMessages, [&$recent = 0], [&$unseen = 0] )
Returns information about messages in the selected mailbox. |
|
public string |
top(
$msgNum, [$chars = 0] )
Returns the headers and the first characters from message $msgNum, without setting the \Seen flag. |
Methods
append
void append(
string
$mailbox, string
$mail, [array(string)
$flags = null] )
Appends $mail to the $mailbox mailbox.
Use this method to create email messages in a mailbox such as Sent or Draft.
$flags is an array of flags to be set to the $mail (if provided): ANSWERED Message has been answered DELETED Message is marked to be deleted by later EXPUNGE DRAFT Message is marked as a draft FLAGGED Message is "flagged" for urgent/special attention SEEN Message has been read This function automatically adds the '\' in front of each flag when calling the server command.
Parameters
| Name |
Type |
Description |
$mailbox |
string |
|
$mail |
string |
|
$flags |
array(string) |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if user is not authenticated or if the server sent a negative response or if $mailbox does not exists |
authenticate
bool authenticate(
string
$user, string
$password )
Authenticates the user to the IMAP server with $user and $password.
This method should be called directly after the construction of this object. If authentication does not succeed, an ezcMailTransportException is thrown. If the server is waiting for authentication process to respond, the connection with the IMAP server will be closed, and false is returned, and it is the application's task to reconnect and reauthenticate.
Parameters
| Name |
Type |
Description |
$user |
string |
|
$password |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if there was no connection to the server or if the provided username/password combination did not work |
capability
array(string) capability(
)
Returns an array with the capabilities of the IMAP server.
Throws
| Class | Description |
|---|
ezcMailTransportException |
if there was no connection to the server or if the server sent a negative response |
clearFlag
bool clearFlag(
string
$messages, string
$flag )
Clears $flag from $messages.
$messages can be:
- a single message number (eg. 1)
- a message range (eg. 1:4)
- a message list (eg. 1,2,4)
$flag can be one of: ANSWERED Message has been answered DELETED Message is marked to be deleted by later EXPUNGE DRAFT Message is marked as a draft FLAGGED Message is "flagged" for urgent/special attention SEEN Message has been read This function automatically adds the '\' in front of the flag when calling the server command.
Parameters
| Name |
Type |
Description |
$messages |
string |
|
$flag |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response or if $flag is not valid |
copyMessages
bool copyMessages(
string
$messages, string
$destination )
Copies message(s) from the selected mailbox to mailbox $destination.
$messages can be:
- a single message number (eg: 1)
- a message range (eg. 1:4)
- a message list (eg. 1,2,4)
Parameters
| Name |
Type |
Description |
$messages |
string |
|
$destination |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if $state is not accepted or if the server sent a negative response |
countByFlag
int countByFlag(
string
$flag )
Wrapper function to fetch count of messages by a certain flag.
$flag can be one of:
- ANSWERED Message has been answered
- DELETED Message is marked to be deleted by later EXPUNGE
- DRAFT Message is marked as a draft
- FLAGGED Message is "flagged" for urgent/special attention
- RECENT Message is recent
- SEEN Message has been read
- UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
Opposites of the above flags
- NEW Equivalent to RECENT + UNSEEN
- ALL All the messages
Parameters
| Name |
Type |
Description |
$flag |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response or if $flag is not valid |
createMailbox
bool createMailbox(
string
$mailbox )
Creates the mailbox $mailbox.
Parameters
| Name |
Type |
Description |
$mailbox |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if $state is not accepted or if the server sent a negative response |
delete
bool delete(
int
$msgNum )
Deletes the message with the message number $msgNum from the server.
The message number must be a valid identifier fetched with e.g. listMessages(). The message is not physically deleted, but has its \Deleted flag set, and can be later undeleted by clearing its \Deleted flag
clearFlag().
Parameters
| Name |
Type |
Description |
$msgNum |
int |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
deleteMailbox
bool deleteMailbox(
string
$mailbox )
Deletes the mailbox $mailbox.
Inbox cannot be deleted.
Parameters
| Name |
Type |
Description |
$mailbox |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if $state is not accepted or if trying to delete the currently selected mailbox or if the server sent a negative response |
disconnect
void disconnect(
)
Disconnects the transport from the IMAP server.
expunge
void expunge(
)
Sends an EXPUNGE command to the server.
This method permanently deletes the messages marked for deletion by the method delete().
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox was not selected or if the server sent a negative response |
fetchAll
Returns a parserset with all the messages on the server.
If $deleteFromServer is set to true the mail will be removed from the server after retrieval. If not it will be left.
Parameters
| Name |
Type |
Description |
$deleteFromServer |
bool |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
fetchByFlag
Fetches messages by a certain flag.
$flag can be one of:
- ANSWERED Message has been answered
- DELETED Message is marked to be deleted by later EXPUNGE
- DRAFT Message is marked as a draft
- FLAGGED Message is "flagged" for urgent/special attention
- RECENT Message is recent
- SEEN Message has been read
- UNANSWERED, UNDELETED, UNDRAFT, UNFLAGGED, OLD, UNSEEN
Opposites of the above flags
- NEW Equivalent to RECENT + UNSEEN
- ALL All the messages
Parameters
| Name |
Type |
Description |
$flag |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response or if $flag is not valid |
fetchByMessageNr
ezcMailImapSet fetchByMessageNr(
int
$number, [bool
$deleteFromServer = false] )
Returns an ezcMailImapSet containing only the $number -th message in the mailbox.
If $deleteFromServer is set to true the mail will be removed from the server after retrieval. If not it will be left. Note: for IMAP the first message is 1 (so for $number = 0 an exception will be thrown).
Parameters
| Name |
Type |
Description |
$number |
int |
|
$deleteFromServer |
bool |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
ezcMailNoSuchMessageException |
if the message $number is out of range |
fetchFlags
array(int=>mixed) fetchFlags(
array
$messages )
Fetches IMAP flags for messages $messages.
$messages is an array of message numbers, for example: array( 1, 2, 4 ); The format of the returned array is: array( message_number => array( flags ) ) Example:
- for
$messages = array( 1, 2, 4 );
- the returned flags are
array( 1 => array( '\Seen' ),
2 => array( '\Seen' ),
4 => array( '\Seen', 'NonJunk' )
);
Parameters
| Name |
Type |
Description |
$messages |
array |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
fetchFromOffset
ezcMailImapSet fetchFromOffset(
int
$offset, [int
$count = 0], [bool
$deleteFromServer = false] )
Returns an ezcMailImapSet with $count messages starting from $offset.
Fetches $count messages starting from the $offset and returns them as a ezcMailImapSet. If $count is not specified or if it is 0, it fetches all messages starting from the $offset.
Parameters
| Name |
Type |
Description |
$offset |
int |
|
$count |
int |
|
$deleteFromServer |
bool |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
ezcMailInvalidLimitException |
if $count is negative. |
ezcMailOffsetOutOfRangeException |
if $offset is outside of the existing range of messages |
listMailboxes
array(int=>string) listMailboxes(
[string
$reference = ''], [string
$mailbox = '*'] )
Lists the available mailboxes on the IMAP server.
Before listing the mailboxes, the connection state ($state) must be at least STATE_AUTHENTICATED or STATE_SELECTED or STATE_SELECTED_READONLY.
For more information about $reference and $mailbox, consult the IMAP RFC document (http://www.faqs.org/rfcs/rfc1730.html). By default, $reference is "" and $mailbox is "*". The array returned contains the mailboxes available for the connected user on this IMAP server. Inbox is a special mailbox, and it can be specified upper-case or lower-case or mixed-case. The other mailboxes should be specified as they are (to the selectMailbox() method).
Parameters
| Name |
Type |
Description |
$reference |
string |
|
$mailbox |
string |
|
Throws
| Class | Description |
|---|
ezcMailMailTransportException |
if $state is not accepted or if the server sent a negative response |
listMessages
array(int=>int) listMessages(
[string
$contentType = null] )
Returns a list of the not deleted messages in the current mailbox.
It returns only the messages with the flag \Deleted not set. The format of the returned array is array(message_id => size). Eg: ( 2 => 1700, 5 => 1450, 6 => 21043 ) If $contentType is set, it returns only the messages with $contentType in the Content-Type header. For example $contentType can be "multipart/mixed" to return only the messages with attachments.
Parameters
| Name |
Type |
Description |
$contentType |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
listUniqueIdentifiers
array(int=>string) listUniqueIdentifiers(
[int
$msgNum = null] )
Returns the unique identifiers messages on the IMAP server.
You can fetch the unique identifier for a specific message only by providing the $msgNum parameter.
The unique identifier can be used to recognize mail from servers between requests. In contrast to the message numbers the unique numbers assigned to an email never changes.
The format of the returned array is array(message_num=>unique_id)
Parameters
| Name |
Type |
Description |
$msgNum |
int |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
noop
void noop(
)
Sends a NOOP command to the server, use it to keep the connection alive.
Throws
| Class | Description |
|---|
ezcMailTransportException |
if there was no connection to the server or if the server sent a negative response |
renameMailbox
bool renameMailbox(
string
$mailbox, string
$newName )
Renames the mailbox $mailbox to $newName.
Inbox cannot be renamed.
Parameters
| Name |
Type |
Description |
$mailbox |
string |
|
$newName |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if $state is not accepted or if trying to rename the currently selected mailbox or if the server sent a negative response |
__construct
ezcMailImapTransport __construct(
string
$server, [int
$port = null], [
$options = array()] )
Creates a new IMAP transport and connects to the $server at $port.
You can specify the $port if the IMAP server is not on the default port 993 (for SSL connections) or 143 (for plain connections). Use the $options parameter to specify an SSL connection.
Parameters
| Name |
Type |
Description |
$server |
string |
|
$port |
int |
|
$options |
array(string=>mixed) |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if it was not possible to connect to the server |
ezcBaseFeatureNotFoundException |
if trying to use SSL and the extension openssl is not installed |
ezcBasePropertyNotFoundException |
if $options contains a property not defined |
ezcBaseValueException |
if $options contains a property with a value not allowed |
__destruct
void __destruct(
)
Destructs the IMAP transport.
If there is an open connection to the IMAP server it is closed.
selectMailbox
void selectMailbox(
string
$mailbox, [bool
$readOnly = false] )
Selects the mailbox $mailbox.
This method should be called after authentication, and before fetching any messages. Before selecting the mailbox, the connection state ($state) must be at least STATE_AUTHENTICATED, STATE_SELECTED or or STATE_SELECTED_READONLY. If the selecting of the mailbox fails (with "NO" or "BAD" response from the server), $state revert to STATE_AUTHENTICATED. After successfully selecting a mailbox, $state will be STATE_SELECTED or STATE_SELECTED_READONLY. Inbox is a special mailbox and can always be specified.
Parameters
| Name |
Type |
Description |
$mailbox |
string |
|
$readOnly |
bool |
|
Throws
| Class | Description |
|---|
ezcMailMailTransportException |
if $state is not accepted or if the server sent a negative response |
setFlag
bool setFlag(
string
$messages, string
$flag )
Sets $flag on $messages.
$messages can be:
- a single message number (eg. 1)
- a message range (eg. 1:4)
- a message list (eg. 1,2,4)
$flag can be one of: ANSWERED Message has been answered DELETED Message is marked to be deleted by later EXPUNGE DRAFT Message is marked as a draft FLAGGED Message is "flagged" for urgent/special attention SEEN Message has been read This function automatically adds the '\' in front of the flag when calling the server command.
Parameters
| Name |
Type |
Description |
$messages |
string |
|
$flag |
string |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response or if $flag is not valid |
sortFromOffset
ezcMailImapSet sortFromOffset(
int
$offset, [int
$count = 0], string
$sortCriteria, [bool
$reverse = false] )
Fetches $count messages from $offset sorted by $sortCriteria.
Fetches $count messages starting from the $offset and returns them as a ezcMailImapSet. If $count is is 0, it fetches all messages starting from the $offset. $sortCriteria is an email header like: Subject, To, From, Date, Sender.
Parameters
| Name |
Type |
Description |
$offset |
int |
|
$count |
int |
|
$sortCriteria |
string |
|
$reverse |
bool |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
ezcMailInvalidLimitException |
if $count is negative |
ezcMailOffsetOutOfRangeException |
if $offset is outside of the existing range of messages |
sortMessages
ezcMailImapSet sortMessages(
array(int=>int)
$messages, string
$sortCriteria, [bool
$reverse = false] )
Fetches messages $messages sorted by $sortCriteria.
$messages is an array of message numbers, for example: array( 1, 2, 4 ); $sortCriteria is an email header like: Subject, To, From, Date, Sender.
Parameters
| Name |
Type |
Description |
$messages |
array(int=>int) |
|
$sortCriteria |
string |
|
$reverse |
bool |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response or if array $messages is empty |
status
bool status(
int
&$numMessages, int
&$sizeMessages, [int
&$recent = 0], [int
&$unseen = 0] )
Returns information about messages in the selected mailbox.
The information returned through parameters is:
- $numMessages = number of not deleted messages in the selected mailbox
- $sizeMessages = sum of the not deleted messages sizes
- $recent = number of recent and not deleted messages
- $unseen = number of unseen and not deleted messages
Parameters
| Name |
Type |
Description |
&$numMessages |
int |
|
&$sizeMessages |
int |
|
&$recent |
int |
|
&$unseen |
int |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
top
string top(
int
$msgNum, [int
$chars = 0] )
Returns the headers and the first characters from message $msgNum, without setting the \Seen flag.
If the command failed or if it was not supported by the server an empty string is returned.
Parameters
| Name |
Type |
Description |
$msgNum |
int |
|
$chars |
int |
|
Throws
| Class | Description |
|---|
ezcMailTransportException |
if a mailbox is not selected or if the server sent a negative response |
Last updated: Thu, 01 Nov 2007
