======================
 Upgrading Horde_Mail
======================

:Contact: dev@lists.horde.org

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


This lists the API changes between releases of the package.


Upgrading to 2.1
================

  - Horde_Mail_Rfc822_Address

    Added the 'bare_address_idn' property.

  - Horde_Mail_Rfc822_List

    Added the 'bare_addresses_idn' property.

  - Horde_Mail_Transport_Smtphorde

    This Transport driver has been added.


Upgrading to 2.0
================

  - Horde_Mail

    This class has been removed (no more Horde_Mail#factory()). Directly
    instantiate a transport driver instead.

  - Horde_Mail_Rfc822

    The 'num_groups' property has been removed.
    The validateMailbox() method has been removed.
    parseAddressList() now returns a Horde_Mail_Rfc822_List object.
    The 'group' parameter to parseAddressList() has been added.
    The 'nest_groups' parameter to parseAddressList() has been removed.
    parseAddressList() does not validate by default.

  - Horde_Mail_Rfc822_Address

    The object can no longer be accessed as an array.
    Removed the 'adl', 'route', and 'personal_decoded' properties.
    The 'personal' property now always returns the MIME decoded personal part.
    The 'host' property now always returns the IDN decoded host.
    The 'encode' and 'idn' parameters to writeAddress() have changed behavior.
    Added the 'host_idn' and 'valid' properties.
    Renamed the 'full_address' property to 'bare_address'.

  - Horde_Mail_Rfc822_Group

    The object can no longer be accessed as an array.
    Removed the 'groupname_decoded' property.
    The 'groupname' property now always returns the MIME decoded groupname.
    The 'encode' and 'idn' parameters to writeAddress() have changed behavior.
    Added the 'valid' property.

  - Horde_Mail_Rfc822_Object

    Added a match() method.
    Passing boolean true to writeAddress() now defaults to full encoding of
    the address.


Upgrading To 1.2
================

Method API additions
--------------------

  - Horde_Mail_Rfc822#parseAddressList()

    The first argument can now be a Horde_Mail_Rfc822_Object or an array of
    address strings and/or Horde_Mail_Rfc822_Objects.

  - Horde_Mail_Rfc822_Address#__construct()

    The constructor now takes 1 optional argument: address.

  - Horde_Mail_Rfc822_Group#__construct()

    The constructor now takes 2 optional arguments: groupname and group
    addresses.


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

  - Horde_Mail_Rfc822#encode()
  - Horde_Mail_Rfc822#trimAddress()


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

  - Horde_Mail_Rfc822_Object

    Horde_Mail_Rfc822_Address and Horde_Mail_Rfc822_Group now extend this
    class.  Allows for easier determination if an object contains RFC 822
    element information.


Upgrading To 1.1
================

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

Horde_Mail_Rfc822::parseAddressList() now returns an array of
Horde_Mail_Rfc822_Address objects (and Horde_Mail_Rfc822_Group objects, if
nest_groups is true).

These objects are backward compatible with the former array representation.
They also include additional functionality.

  - Horde_Mail_Rfc822_Address

    Anything other than accessing these properties is a new feature available
    only since 1.1.0:

    - adl
    - comment
    - host
    - mailbox
    - personal

  - Horde_Mail_Rfc822_Group

    Anything other than accessing these properties is a new feature available
    only since 1.1.0:

    - addresses
    - groupname
