=============================
 Upgrading Horde_Imap_Client
=============================

:Contact: dev@lists.horde.org

.. contents:: Contents
.. section-numbering::


This lists the API changes between minor releases of the package.

Upgrading To 1.4.0
==================

Several exception codes have been deprecated:

  - DRIVER_NOT_FOUND
  - CATENATE_BADURL
  - BADSEARCH

These are coding errors, not run-time errors, so SPL Exceptions are thrown
instead of Horde_Imap_Client_Exceptions with these codes.

These exception codes have also been deprecated:

  - NOSUPPORTIMAPEXT
  - POP3_NOTSUPPORTED

Instead, a Horde_Imap_Client_Exception_NoSupportExtension will be thrown. This
class is an extension of Horde_Imap_Client_Exception, so current try/catch
statements will automatically catch these exceptions.

Horde_Imap_Client_Exception messages are now translated.  Additionally, debug
information from the server MAY be available in the 'details' property of the
Exception object rather than being added to the error message.


Upgrading To 1.3.0
==================

The Cclient drivers have been removed; they are instead mapped to the
appropriate Socket drivers.  No code needs to be changed for now as this will
happen automatically.  However, the 'Cclient' and 'Cclient_Pop3' driver names
are deprecated and will be removed in 2.0.0.


Upgrading To 1.2.0
==================

There has been a major change in the way mailbox names are handled in this
version.  Due to ambiguities with auto-detecting UTF-8 vs. UTF7-IMAP, all
mailbox method parameters and return values are now Horde_Imap_Client_Mailbox
objects.  These objects, when cast to a string, will return the UTF-8 version
of the mailbox.

All other non-mailbox strings that previously could be passed in as either
UTF7-IMAP or UTF-8 are now REQUIRED to be passed in as UTF-8.

Auto-detection will still work, but is deprecated, will be removed in 2.0.0,
and is not guaranteed to produce proper results for all mailbox names.


Changed Return Values
---------------------

The following return values have changed:

  - Horde_Imap_Client_Base#currentMailbox()

    If the 'utf8' parameter is true, a Horde_Imap_Client_Mailbox object
    will be returned (an equivalent string representation to the previous
    behavior of returning a UTF-8 string).

  - Horde_Imap_Client_Base#getNamespaces()

    The return array keys and the 'name' parameter are returned in UTF7-IMAP
    (the documentation was previously unclear as to the charset of these
    items).

  - Horde_Imap_Client_Base#listMailboxes()

    If both the 'flat' and 'utf8' parameters are true, the array values will
    be Horde_Imap_Client_Mailbox objects, instead of a string (an equivalent
    string representation to the previous behavior of returning a UTF-8
    string).

    If the 'flat' parameter is false and the 'utf8' parameter is true, the
    'mailbox' array key will be a Horde_Imap_Client_Mailbox object instead of
    a string (an equivalent string representation to the previous behavior of
    returning a UTF-8 string).

  - Horde_Imap_Client_Base#statusMultiple()

    The return array keys are returned in UTF7-IMAP (the documentation was
    previously unclear as to the charset of these keys).

Deprecated Methods
------------------

The following methods are deprecated and will be removed in 2.0.0:

  - Horde_Imap_Client_Cache::singleton()

    Use Horde_Imap_Client_Cache::factory() instead.

  - Horde_Imap_Client_Base#parseCommandArray()

    Use Horde_Imap_Client_Utils#parseCommandArray() instead.

Deprecated Parameters
------------------

  - Horde_Imap_Client_Base#currentMailbox()

    The 'utf8' parameter has been deprecated. The 'mailbox' return value will
    exclusively return a Horde_Imap_Client_Mailbox object in 2.0.0.

Drivers
-------

The unmaintained Mock driver has been removed.

Method Parameter Changes
------------------------

  - Horde_Imap_Client_Base#append()
  - Horde_Imap_Client_Base#copy()
  - Horde_Imap_Client_Base#createMailbox()
  - Horde_Imap_Client_Base#deleteMailbox()
  - Horde_Imap_Client_Base#expunge()
  - Horde_Imap_Client_Base#fetch()
  - Horde_Imap_Client_Base#fetchFromSectionString()
  - Horde_Imap_Client_Base#getACL()
  - Horde_Imap_Client_Base#getCacheId()
  - Horde_Imap_Client_Base#getMetadata()
  - Horde_Imap_Client_Base#getMyACLRights()
  - Horde_Imap_Client_Base#getQuota()
  - Horde_Imap_Client_Base#getQuotaRoot()
  - Horde_Imap_Client_Base#listACLRights()
  - Horde_Imap_Client_Base#openMailbox()
  - Horde_Imap_Client_Base#renameMailbox()
  - Horde_Imap_Client_Base#search()
  - Horde_Imap_Client_Base#setACL()
  - Horde_Imap_Client_Base#setMetadata()
  - Horde_Imap_Client_Base#setQuota()
  - Horde_Imap_Client_Base#status()
  - Horde_Imap_Client_Base#statusMultiple()
  - Horde_Imap_Client_Base#store()
  - Horde_Imap_Client_Base#subscribeMailbox()
  - Horde_Imap_Client_Base#thread()

    These methods now require the mailbox parameter(s) to be passed in as
    either a Horde_Imap_Client_Mailbox object (RECOMMENDED) or a UTF-8
    string. Passing in a UTF7-IMAP string is DEPRECATED and will be removed
    in 2.0.0. (The limitation of allowing UTF7-IMAP strings to be continued
    to be passed in for now is that auto-detection remains necessary. Passing
    in UTF-8 strings will thus break for certain mailbox names - the only
    way to guarantee proper mailbox handling for 1.2.0+ is to pass in Mailbox
    objects.)

  - Horde_Imap_Client_Base#getMetadata()

    The $entries parameter now requires the entries to be passed in as
    UTF-8 strings ONLY (UTF7-IMAP no longer allowed). Auto-detection will be
    removed in 2.0.0. To ensure proper mailbox handling in 1.2.0+, you can pass
    the entries as Horde_Imap_Client_Mailbox objects.

  - Horde_Imap_Client_Base#getNamespaces()

    The $additional parameter now requires the namespaces to be passed in as
    UTF-8 strings ONLY (UTF7-IMAP no longer allowed). Auto-detection will be
    removed in 2.0.0. To ensure proper mailbox handling in 1.2.0+, you can pass
    the namespace names as Horde_Imap_Client_Mailbox objects.

  - Horde_Imap_Client_Base#listMailboxes()

    The $pattern parameter now requires the patterns to be passed in as
    UTF-8 strings ONLY (UTF7-IMAP no longer allowed). Auto-detection will be
    removed in 2.0.0. To ensure proper mailbox handling in 1.2.0+, you can pass
    the patterns as Horde_Imap_Client_Mailbox objects.

    The 'utf8' parameter has been removed.

  - Horde_Imap_Client_Base#listACLRights()
  - Horde_Imap_Client_Base#setACL()

    The $identifier parameter now requires the identifiers to be passed in as
    UTF-8 strings ONLY (UTF7-IMAP no longer allowed). Auto-detection will be
    removed in 1.3. To ensure proper mailbox handling in 1.2.0+, you can pass
    the identifiers as Horde_Imap_Client_Mailbox objects.

  - Horde_Imap_Client_Cache#__construct()

    A new required parameter 'baseob' has been added. This replaces the
    'hostspec', 'port', and 'username' parameters, which are deprecated and
    will be removed in 2.0.0.

    The 'debug' parameter is now a boolean indicating whether debugging is
    desired; debug output is now controlled via the Base object passed in
    through 'baseob'. The old usage - passing in a resource - is IMMEDIATELY
    deprecated and will be ignored.

  - Horde_Imap_Client_Utf7imap::Utf8ToUtf7Imap()

    Added the $force parameter.

New Methods
-----------

  - Horde_Imap_Client_Base#getIdsOb()
  - Horde_Imap_Client_Base#writeDebug()

New Objects
-----------

  - Horde_Imap_Client_Ids
  - Horde_Imap_Client_Ids_Pop3
  - Horde_Imap_Client_Mailbox
  - Horde_Imap_Client_Utils_Pop3



Upgrading To 1.1.0
==================

New Object Properties
---------------------

  - Horde_Imap_Client_Data_Envelope

    Added properties to obtain MIME decoded envelope information. New
    properties: 'bcc_decoded', 'cc_decoded', 'from_decoded',
    'reply_to_decoded', 'sender_decoded', 'subject_decoded', 'to_decoded'
