Documentation

Tutorial

Autoloading

Horde/Imap_Client does not include() its own files, so an autoloader must be registered that will load the Horde/Imap_Client files from its PEAR directory. Horde's Autoloader package can be used to do this for you (or any other PSR-0 compliant autoloader).

Constructor

Interaction with the mail server is handled through a Horde_Imap_Client_Base object. The object class will be one of the following:

The minimum necessary configuration needed for the Client constructor is the username and password. Although default values can be used for the hostspec, port, and secure options, it is generally a good idea to explicitly set these values to aid in debugging connection issues.

Debugging

Debug output of the server protocol communication can be obtained by providing the 'debug' option. Acceptable values are any PHP supported wrapper that can be opened via the fopen() command. A plain string is inerpreted as a filename, which is probably what most people will want to use.

Caching

TODO

Example

A sample constructor instantation (all further examples assume that this command has been performed and a client object is present in the $client variable):

The full list of options can be found in the API Documentation.

Error Handling/Exceptions

As noted in the constructor example, all errors encountered by the library will cause exceptions of the Horde_Imap_Client_Exception class (or a subclass of this base class) to be thrown.

The exception message will contain a translated version of the error message. If the "raw" English version of the message is needed - i.e. for logging purposes - it can be found in the $raw_msg property.

Further server debug information might be found in the $details property.

Working with a Single Mailbox

The following examples assume that the user wants to work with the messages contained in their INBOX.

Loading Mailbox

There is no need to provide commands to login and/or switch to a mailbox. These actions are handled on-demand by the library.

NOTE: All mailbox arguments to methods in Horde/Imap_Client take the UTF-8 version of the mailbox name. There is no need to worry about converting from/to the internal UTF7-IMAP charset used on IMAP servers.

Alternatively, you can use Horde_Imap_Client_Mailbox objects as the mailbox argument. This object can automatically convert the mailbox name if in UTF7-IMAP for you. Example:

Listing Messages

The search() command is used to list the messages in a mailbox. It only requires a mailbox name for basic usage, and will return a list of unsorted UIDs in the mailbox.

To filter the list of messages returned by search(), a Horde_Imap_Client_Search_Query object can be passed as the second parameter to search(). If not present, all messages in the mailbox are returned.

The third argument to search() allows additional search parameters to be specified, such as the prefered sort order.

In the examples above, $uids is a Horde_Imap_Client_Ids object (all message ID lists are returned via this object in Horde/Imap_Client). This object implements both the Countable and Traversable classes, so it can be used directly in count() and foreach() commands. If a raw array is needed, it can be obtained from the object via the $ids property.