eZ Components 2007.2beta1

Getting Started

Components

Archive (1.2.4)
Authentication (1.1beta1)
AuthenticationDatabaseTiein (1.1beta1)
Base (1.4beta1)
Cache (1.3beta1)
Configuration (1.2)
ConsoleTools (1.3.1)
Database (1.3.2)
DatabaseSchema (1.3beta1)
Debug (1.1)
EventLog (1.2beta1)
EventLogDatabaseTiein (1.0.2)
Execution (1.1beta1)
Feed (1.0beta1)
File (1.2beta1)
Graph (1.2beta1)
GraphDatabaseTiein (1.0)
ImageAnalysis (1.1.2)
ImageConversion (1.3.1)
Mail (1.4beta1)
PersistentObject (1.3.2)
PersistentObjectDatabaseSchemaTiein (1.2.1)
PhpGenerator (1.0.4)
SignalSlot (1.1)
SystemInformation (1.0.5)
Template (1.2)
Translation (1.1.5)
TranslationCacheTiein (1.1.2)
Tree (1.0beta1)
TreeDatabaseTiein (1.0beta1)
TreePersistentObjectTiein (1.0beta1)
Url (1.2beta1)
UserInput (1.2beta1)
Webdav (1.0beta1)
Workflow (1.1beta1)
WorkflowDatabaseTiein (1.1beta1)
WorkflowEventLogTiein (1.1beta1)

Mail: ezcMailImapTransport

[ Tutorial ] [ Display example ] [ Mail listing example ] [ Rfcs ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcMailImapTransport

The class ezcMailImapTransport implements functionality for handling IMAP mail servers. [source]

The implementation supports most of the commands specified in:

http://www.faqs.org/rfcs/rfc1730.html (IMAP4)
http://www.faqs.org/rfcs/rfc2060.html (IMAP4rev1)

Each user account on the IMAP server has it's own folders (mailboxes). Mailboxes can be created, renamed or deleted. All accounts have a special mailbox called Inbox which cannot be deleted or renamed.

Messages are organized in mailboxes, and are identified by a message number (which can change over time) and a unique ID (which does not change under normal circumstances). The commands operating on messages can handle both modes (message numbers or unique IDs).

Messages are marked by certain flags (SEEN, DRAFT, etc). Deleting a message actually sets it's DELETED flag, and a later call to expunge() will delete all the messages marked with the DELETED flag.

The IMAP server can be in different states. Most IMAP commands require that a connection is established and a user is authenticated. Certain commands require in addition that a mailbox is selected.

The IMAP transport class allows developers to interface with an IMAP server. The commands which support unique IDs to refer to messages are marked with [*] (see ezcMailImapTransportOptions to find out how to enable unique IDs referencing):

Basic commands:

connect to an IMAP server (__construct())
authenticate a user with a username and password (authenticate())
select a mailbox (selectMailbox())
disconnect from the IMAP server (disconnect())

Work with mailboxes:

get the list of mailboxes of the user (listMailboxes())
create a mailbox (createMailbox()
rename a mailbox (renameMailbox()
delete a mailbox (deleteMailbox()
append a message to a mailbox (append()
select a mailbox (selectMailbox())
get the status of messages in the current mailbox (status())
get the number of messages with a certain flag (countByFlag()

Work with message numbers (on the currently selected mailbox):

get the message numbers and sizes of all the messages (listMessages())
get the message numbers and IDs of all the messages (listUniqueIdentifiers())
[*] get the headers of a certain message (top())
[*] delete a message (delete() and expunge())
[*] copy messages to another mailbox (copyMessages())
[*] get the sizes of the specified messages (fetchSizes())

Work with flags (on the currently selected mailbox):

[*] get the flags of the specified messages (fetchFlags())
[*] set a flag on the specified messages (setFlag())
[*] clear a flag from the specified messages (clearFlag())

Work with ezcMailImapSet sets (parseable with ezcMailParser) (on the currently selected mailbox):

[*] create a set from all messages (fetchAll())
[*] create a set from a certain message (fetchByMessageNr())
[*] create a set from a range of messages (fetchFromOffset())
[*] create a set from messages with a certain flag (fetchByFlag())
[*] create a set from a sorted range of messages (sortFromOffset())
[*] create a set from a sorted list of messages (sortMessages())
[*] create a set from a free-form search (searchMailbox())

Miscellaneous commands:

get the capabilities of the IMAP server (capability())
get the hierarchy delimiter (useful for nested mailboxes) (getHierarchyDelimiter())
issue a NOOP command to keep the connection alive (noop())

The usual operation with an IMAP server is illustrated by this example:

 1.  // create a new IMAP transport object by specifying the server name, optional port
 2.  // and optional SSL mode
 3.   $options = new ezcMailImapTransportOptions();
 4.  $options->ssl = true;
 5.  $imap = new ezcMailImapTransport( 'imap.example.com', null, $options );
 6.  
 7.  // Authenticate to the IMAP server
 8.   $imap->authenticate( 'username', 'password' );
 9.  
10.  // Select a mailbox (here 'Inbox')
11.   $imap->selectMailbox( 'Inbox' );
12.  
13.  // issue commands to the IMAP server
14.  // for example get the number of RECENT messages
15.   $recent = $imap->countByFlag( 'RECENT' );
16.  
17.  // see the above list of commands or consult the online documentation for
18.  // the full list of commands you can issue to an IMAP server and examples
19.  
20.  // disconnect from the IMAP server
21.   $imap->disconnect();

See ezcMailImapTransportOptions for other options you can specify for IMAP.

Properties

ezcMailImapTransportOptions

read/write

$options

Holds the options you can set to the IMAP transport.

Member Variables

protected array(string)	`$basicFlags = array( 'ANSWERED', 'DELETED', 'DRAFT', 'FLAGGED', 'SEEN' )` Basic flags are used by setFlag() and clearFlag()
protected ezcMailTransportConnection	`$connection = null` Holds the connection to the IMAP server.
protected string	`$currentTag = 'A0000'` Used to generate a tag for sending commands to the IMAP server.
protected array(string)	`$extendedFlags = array( 'ALL', 'ANSWERED', 'DELETED', 'DRAFT', 'FLAGGED', 'NEW', 'OLD', 'RECENT', 'SEEN', 'UNANSWERED', 'UNDELETED', 'UNDRAFT', 'UNFLAGGED', 'UNRECENT', 'UNSEEN' )` Extended flags are used by searchByFlag()
protected string	`$selectedMailbox = null` Holds the currently selected mailbox.
protected int	`$state = self::STATE_NOT_CONNECTED` Holds the connection state.

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 currently 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 current mailbox.
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 an ezcMailImapSet with all the messages from the current mailbox.
public ezcMailImapSet	`fetchByFlag( $flag )` Returns an ezcMailImapSet containing messages with a certain flag from the current mailbox.
public ezcMailImapSet	`fetchByMessageNr( $number, [$deleteFromServer = false] )` Returns an ezcMailImapSet containing only the $number -th message in the current mailbox.
public array(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 from the current mailbox.
public array(int)	`fetchSizes( $messages )` Fetches the sizes in bytes for messages $messages.
public string	`getHierarchyDelimiter( )` Returns the hierarchy delimiter of the IMAP server, useful for handling nested IMAP folders.
protected string	`getNextTag( )` Generates the next IMAP tag to prepend to client commands.
protected string	`getResponse( $tag, [$response = null] )` Reads the responses from the server until encountering $tag.
public array(string)	`listMailboxes( [$reference = ''], [$mailbox = '*'] )` Returns an array with the names of the available mailboxes for the user currently authenticated on the IMAP server.
public array(int)	`listMessages( [$contentType = null] )` Returns a list of the not deleted messages in the current mailbox.
public array(string)	`listUniqueIdentifiers( [$msgNum = null] )` Returns the unique identifiers for the messages from the current mailbox.
public void	`noop( )` Sends a NOOP command to the server, use it to keep the connection alive.
protected string	`normalizeFlag( $flag )` Clears $flag of unwanted characters and makes it uppercase.
public bool	`renameMailbox( $mailbox, $newName )` Renames the mailbox $mailbox to $newName.
protected int	`responseType( $line )` Parses $line to return the response code.
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.
protected array(int)	`searchByFlag( $flag )` Returns an array of message numbers from the selected mailbox which have a certain flag set.
public ezcMailImapSet	`searchMailbox( [$criteria = null] )` Returns an ezcMailImapSet containing the messages which match the provided $criteria from the current mailbox.
public void	`selectMailbox( $mailbox, [$readOnly = false] )` Selects the mailbox $mailbox, which will be the active mailbox for the subsequent commands until it is changed.
public bool	`setFlag( $messages, $flag )` Sets $flag on $messages.
protected array(string)	`sort( $messages, $sortCriteria, [$reverse = false] )` Sorts message numbers array $messages by the specified $sortCriteria.
public ezcMailImapSet	`sortFromOffset( $offset, [$count = 0], $sortCriteria, [$reverse = false] )` Returns an ezcMailImapSet containing $count messages starting from $offset sorted by $sortCriteria from the current mailbox.
public ezcMailImapSet	`sortMessages( $messages, $sortCriteria, [$reverse = false] )` Returns an ezcMailImapSet containing messages $messages sorted by $sortCriteria from the current mailbox.
public bool	`status( &$numMessages, &$sizeMessages, [&$recent = 0], [&$unseen = 0] )` Returns information about the messages in the current 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):

$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 each flag when calling the server command.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

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 the server is waiting for the 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.

Example of creating an IMAP transport and authenticating:

1.  // replace with your IMAP server address
2.   $imap = new ezcMailImapTransport( 'imap.example.com' );
3.  
4.  // replace the values with your username and password for the IMAP server
5.   $imap->authenticate( 'username', 'password' );

Parameters

Name	Type	Description
`$user`	string
`$password`	string

Throws

Class	Description
`ezcMailTransportException`	if already authenticated or if the provided username/password combination did not work

capability

array(string) capability( )

Returns an array with the capabilities of the IMAP server.

The returned array will be something like this:

1.    array( 'IMAP4rev1', 'SASL-IR SORT', 'THREAD=REFERENCES', 'MULTIAPPEND',
2.           'UNSELECT', 'LITERAL+', 'IDLE', 'CHILDREN', 'NAMESPACE',
3.           'LOGIN-REFERRALS'
4.         );

Before calling this method, a connection to the IMAP server must be established.

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.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$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.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
4.  
5.  $imap->clearFlag( '1:4', 'DRAFT' );

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 currently selected mailbox to mailbox $destination.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

Warning! When using unique IDs referencing and trying to copy a message with an ID that does not exist, this method will not throw an exception.

Parameters

Name	Type	Description
`$messages`	string
`$destination`	string

Throws

Class	Description
`ezcMailTransportException`	if the current server 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:

Basic flags:

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

Opposites of the above flags:

UNANSWERED
UNDELETED
UNDRAFT
UNFLAGGED
OLD
UNSEEN

Composite flags:

NEW - equivalent to RECENT + UNSEEN
ALL - all the messages

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

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.

Inbox cannot be created.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Parameters

Name	Type	Description
`$mailbox`	string

Throws

Class	Description
`ezcMailTransportException`	if the current server 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 current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

The message number $msgNum 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 with clearFlag().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

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 and the the currently selected mailbox cannot be deleted.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Parameters

Name	Type	Description
`$mailbox`	string

Throws

Class	Description
`ezcMailTransportException`	if the current server 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().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Throws

Class	Description
`ezcMailTransportException`	if a mailbox was not selected or if the server sent a negative response

fetchAll

ezcMailParserSet fetchAll( [bool $deleteFromServer = false] )

Returns an ezcMailImapSet with all the messages from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If $deleteFromServer is set to true the mail will be marked for deletion after retrieval. If not it will be left intact.

The set returned can be parsed with ezcMailParser.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

 1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
 2.  $imap->authenticate( 'username', 'password' );
 3.  $imap->selectMailbox( 'Inbox' );
 4.  
 5.  $set = $imap->fetchAll();
 6.  
 7.  // parse $set with ezcMailParser
 8.   $parser = new ezcMailParser();
 9.  $mails = $parser->parseMail( $set );
10.  foreach ( $mails as $mail )
11.  {
12.      // process $mail which is an ezcMail object
13.   }

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

ezcMailImapSet fetchByFlag( string $flag )

Returns an ezcMailImapSet containing messages with a certain flag from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$flag can be one of:

Basic flags:

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

Opposites of the above flags:

UNANSWERED
UNDELETED
UNDRAFT
UNFLAGGED
OLD
UNSEEN

Composite flags:

NEW - equivalent to RECENT + UNSEEN
ALL - all the messages

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
5.  // Fetch the messages marked with the RECENT flag
6.   $set = $imap->fetchByFlag( 'RECENT' );
7.  
7.  // $set can be parsed with ezcMailParser

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 current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If $deleteFromServer is set to true the mail will be marked for deletion after retrieval. If not it will be left intact.

Note: for IMAP the first message is 1 (so for $number = 0 an exception will be thrown).

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'Inbox' );
4.  
5.  $set = $imap->fetchByMessageNr( 1 );
6.  
6.  // $set can be parsed with ezcMailParser

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(mixed) fetchFlags( array $messages )

Fetches IMAP flags for messages $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1.    array( 1, 2, 4 );

The format of the returned array is:

1.    array( message_number => array( flags ) )

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
4.  
5.  $flags = $imap->fetchFlags( array( 1, 2, 4 ) );

The returned array $flags will be something like:

1.    array( 1 => array( '\Seen' ),
2.           2 => array( '\Seen' ),
3.           4 => array( '\Seen', 'NonJunk' )
4.         );

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 from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

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.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'Inbox' );
4.  
5.  $set = $imap->fetchFromOffset( 1, 10 );
6.  
6.  // $set can be parsed with ezcMailParser

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

fetchSizes

array(int) fetchSizes( array $messages )

Fetches the sizes in bytes for messages $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1.    array( 1, 2, 4 );

The format of the returned array is:

1.    array( message_number => size )

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
4.  
5.  $sizes = $imap->fetchSizes( array( 1, 2, 4 ) );

The returned array $sizes will be something like:

1.    array( 1 => 1043,
2.           2 => 203901,
3.           4 => 14277
4.         );

Parameters

Name	Type	Description
`$messages`	array

Throws

Class	Description
`ezcMailTransportException`	if a mailbox is not selected or if the server sent a negative response

getHierarchyDelimiter

string getHierarchyDelimiter( )

Returns the hierarchy delimiter of the IMAP server, useful for handling nested IMAP folders.

For more information about the hierarchy delimiter, consult the IMAP RFCs http://www.faqs.org/rfcs/rfc1730.html or http://www.faqs.org/rfcs/rfc2060.html, section 6.3.8.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Example of returning the hierarchy delimiter:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  
4.  $delimiter = $imap->getDelimiter();

After running the above code, $delimiter should be something like "/".

Throws

Class	Description
`ezcMailMailTransportException`	if the current server state is not accepted or if the server sent a negative response

getNextTag

string getNextTag( )

Generates the next IMAP tag to prepend to client commands.

The structure of the IMAP tag is Axxxx, where:

A is a letter (uppercase for conformity)
x is a digit from 0 to 9

example of generated tag: T5439

It uses the class variable $this->currentTag.

Everytime it is called, the tag increases by 1.

If it reaches the last tag, it wraps around to the first tag.

By default, the first generated tag is A0001.

getResponse

string getResponse( string $tag, [string $response = null] )

Reads the responses from the server until encountering $tag.

In IMAP, each command sent by the client is prepended with a alphanumeric tag like 'A1234'. The server sends the response to the client command as lines, and the last line in the response is prepended with the same tag, and it contains the status of the command completion ('OK', 'NO' or 'BAD').

Sometimes the server sends alerts and response lines from other commands before sending the tagged line, so this method just reads all the responses until it encounters $tag.

It returns the tagged line to be processed by the calling method.

If $response is specified, then it will not read the response from the server before searching for $tag in $response.

Before calling this method, a connection to the IMAP server must be established.

Parameters

Name	Type	Description
`$tag`	string
`$response`	string

listMailboxes

array(string) listMailboxes( [string $reference = ''], [string $mailbox = '*'] )

Returns an array with the names of the available mailboxes for the user currently authenticated on the IMAP server.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

For more information about $reference and $mailbox, consult the IMAP RFCs documents (http://www.faqs.org/rfcs/rfc1730.html or http://www.faqs.org/rfcs/rfc2060.html, section 7.2.2.).

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).

Example of listing mailboxes:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  
4.  $mailboxes = $imap->listMailboxes();

Parameters

Name	Type	Description
`$reference`	string
`$mailbox`	string

Throws

Class	Description
`ezcMailMailTransportException`	if the current server state is not accepted or if the server sent a negative response

listMessages

array(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.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

The format of the returned array is

1.    array( message_id => size );

Example:

1.    array( 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(string) listUniqueIdentifiers( [int $msgNum = null] )

Returns the unique identifiers for the messages from the current mailbox.

You can fetch the unique identifier for a specific message 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 usually never changes.

The format of the returned array is:

1.    array( message_num => unique_id );

Example:

1.    array( 1 => 216, 2 => 217, 3 => 218, 4 => 219 );

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

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.

Before calling this method, a connection to the IMAP server must be established.

Throws

Class	Description
`ezcMailTransportException`	if there was no connection to the server or if the server sent a negative response

normalizeFlag

string normalizeFlag( string $flag )

Clears $flag of unwanted characters and makes it uppercase.

Parameters

Name	Type	Description
`$flag`	string

renameMailbox

bool renameMailbox( string $mailbox, string $newName )

Renames the mailbox $mailbox to $newName.

Inbox cannot be renamed.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Parameters

Name	Type	Description
`$mailbox`	string
`$newName`	string

Throws

Class	Description
`ezcMailTransportException`	if the current server state is not accepted or if trying to rename the currently selected mailbox or if the server sent a negative response

responseType

int responseType( string $line )

Parses $line to return the response code.

Returns one of the following:

RESPONSE_OK
RESPONSE_NO
RESPONSE_BAD
RESPONSE_UNTAGGED
RESPONSE_FEEDBACK

Parameters

Name	Type	Description
`$line`	string

Throws

Class	Description
`ezcMailTransportException`	if the IMAP response ($line) is not recognized

__construct

ezcMailImapTransport __construct( string $server, [int $port = null], [ezcMailImapTransportOptions|array(string=>mixed) $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.

See ezcMailImapTransportOptions for options you can specify for IMAP.

Example of creating an IMAP transport:

1.  // replace with your IMAP server address
2.   $imap = new ezcMailImapTransport( 'imap.example.com' );
3.  
4.  // if you want to use SSL:
5.   $options = new ezcMailImapTransportOptions();
6.  $options->ssl = true;
7.  
8.  $imap = new ezcMailImapTransport( 'imap.example.com', null, $options );

Parameters

Name	Type	Description
`$server`	string
`$port`	int
`$options`	ezcMailImapTransportOptions\|array(string=>mixed)

Throws

Class	Description
`ezcMailTransportException`	if it was not possible to connect to the server
`ezcBaseExtensionNotFoundException`	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.

searchByFlag

array(int) searchByFlag( string $flag )

Returns an array of message numbers from the selected mailbox which have a certain flag set.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$flag can be one of:

Basic flags:

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

Opposites of the above flags:

UNANSWERED
UNDELETED
UNDRAFT
UNFLAGGED
OLD
UNSEEN

Composite flags:

NEW - equivalent to RECENT + UNSEEN
ALL - all the messages

The returned array is something like this:

1.    array( 0 => 1, 1 => 5 );

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

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

searchMailbox

ezcMailImapSet searchMailbox( [string $criteria = null] )

Returns an ezcMailImapSet containing the messages which match the provided $criteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

See http://www.faqs.org/rfcs/rfc1730.html

6.4.4. (or http://www.faqs.org/rfcs/rfc1730.html - 6.4.4.) for criterias

which can be used for searching. The criterias can be combined in the same search string (separate the criterias with spaces).

If $criteria is null or empty then it will default to 'ALL' (returns all messages in the mailbox).

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Examples:

 1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
 2.  $imap->authenticate( 'username', 'password' );
 3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
 4.  
 5.  // return an ezcMailImapSet containing all messages flagged as 'SEEN'
 6.   $set = $imap->searchMailbox( 'SEEN' );
 7.  
 8.  // return an ezcMailImapSet containing messages with 'release' in their Subject
 9.   $set = $imap->searchMailbox( 'SUBJECT "release"' );
10.  
11.  // criterias can be combined:
12.  // return an ezcMailImapSet containing messages flagged as 'SEEN' and
13.  // with 'release' in their Subject
14.   $set = $imap->searchMailbox( 'SEEN SUBJECT "release"' );
15.  
15.  // $set can be parsed with ezcMailParser

Parameters

Name	Type	Description
`$criteria`	string

Throws

Class	Description
`ezcMailTransportException`	if a mailbox is not selected or if the server sent a negative response

selectMailbox

void selectMailbox( string $mailbox, [bool $readOnly = false] )

Selects the mailbox $mailbox, which will be the active mailbox for the subsequent commands until it is changed.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully.

Inbox is a special mailbox and can be specified with any case.

This method should be called after authentication, and before fetching any messages.

Example of selecting a mailbox:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  
4.  $imap->selectMailbox( 'Reports 2006' );

Parameters

Name	Type	Description
`$mailbox`	string
`$readOnly`	bool

Throws

Class	Description
`ezcMailMailTransportException`	if the current server state is not accepted or if the server sent a negative response

setFlag

bool setFlag( string $messages, string $flag )

Sets $flag on $messages.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$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.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
4.  
5.  $imap->setFlag( '1:4', 'DRAFT' );

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

sort

array(string) sort( array(int) $messages, string $sortCriteria, [bool $reverse = false] )

Sorts message numbers array $messages by the specified $sortCriteria.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1.    array( 1, 2, 4 );

$sortCriteria is an email header like: Subject, To, From, Date, Sender.

The sorting is done with the php function natcasesort().

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Parameters

Name	Type	Description
`$messages`	array(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 the array $messages is empty

sortFromOffset

ezcMailImapSet sortFromOffset( int $offset, [int $count = 0], string $sortCriteria, [bool $reverse = false] )

Returns an ezcMailImapSet containing $count messages starting from $offset sorted by $sortCriteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

It is useful for paging through a mailbox.

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, etc.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
5.  // Fetch a range of messages sorted by Date
6.   $set = $imap->sortFromOffset( 1, 10, "Date" );
7.  
7.  // $set can be parsed with ezcMailParser

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) $messages, string $sortCriteria, [bool $reverse = false] )

Returns an ezcMailImapSet containing messages $messages sorted by $sortCriteria from the current mailbox.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

$messages is an array of message numbers, for example:

1.    array( 1, 2, 4 );

$sortCriteria is an email header like: Subject, To, From, Date, Sender, etc.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'mailbox' ); // Inbox or another mailbox
4.  
5.  // Fetch the list of messages sorted by Date
6.   $set = $imap->sortMessages( 1, 10, "Date" );
7.  
7.  // $set can be parsed with ezcMailParser

Parameters

Name	Type	Description
`$messages`	array(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 the messages in the current mailbox.

The information returned through the 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

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example of returning the status of the currently selected mailbox:

1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
2.  $imap->authenticate( 'username', 'password' );
3.  $imap->selectMailbox( 'Inbox' );
4.  
5.  $imap->status( $numMessages, $sizeMessages, $recent, $unseen );

After running the above code, $numMessages, $sizeMessages, $recent and $unseen will be populated with values.

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.

This method supports unique IDs instead of message numbers. See ezcMailImapTransportOptions for how to enable unique IDs referencing.

If the command failed or if it was not supported by the server an empty string is returned.

This method is useful for retrieving the headers of messages from the mailbox as strings, which can be later parsed with ezcMailParser and ezcMailVariableSet. In this way the retrieval of the full messages from the server is avoided when building a list of messages.

Before calling this method, a connection to the IMAP server must be established and a user must be authenticated successfully, and a mailbox must be selected.

Example of listing the mail headers of all the messages in the current mailbox:

 1.  $imap = new ezcMailImapTransport( 'imap.example.com' );
 2.  $imap->authenticate( 'username', 'password' );
 3.  $imap->selectMailbox( 'Inbox' );
 4.  
 5.  $parser = new ezcMailParser();
 6.  $messages = $imap->listMessages();
 7.  foreach ( $messages as $messageNr => $size )
 8.  {
 9.      $set = new ezcMailVariableSet( $imap->top( $messageNr ) );
10.      $mail = $parser->parseMail( $set );
11.      $mail = $mail[0];
12.      echo "From: {$mail->from}, Subject: {$mail->subject}, Size: {$size}\n";
13.  }

For a more advanced example see the "Mail listing example" in the online documentation.

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: Wed, 28 Nov 2007

eZ Components

User menu

Path

eZ Components 2007.2beta1

Getting Started

Components

Mail: ezcMailImapTransport

Class: ezcMailImapTransport

Properties

Member Variables

Method Summary

Methods

append

Parameters

Throws

authenticate

Parameters

Throws

capability

Throws

clearFlag

Parameters

Throws

copyMessages

Parameters

Throws

countByFlag

Parameters

Throws

createMailbox

Parameters

Throws

delete

Parameters

Throws

deleteMailbox

Parameters

Throws

disconnect

expunge

Throws

fetchAll

Parameters

Throws

fetchByFlag

Parameters

Throws

fetchByMessageNr

Parameters

Throws

fetchFlags

Parameters

Throws

fetchFromOffset

Parameters

Throws

fetchSizes

Parameters

Throws

getHierarchyDelimiter

Throws

getNextTag

getResponse

Parameters

listMailboxes

Parameters

Throws

listMessages

Parameters

Throws

listUniqueIdentifiers

Parameters

Throws

noop

Throws

normalizeFlag

Parameters

renameMailbox

Parameters

Throws