=============================
 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.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'
