===============
 Upgrading IMP
===============

:Contact: imp@lists.horde.org

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


General instructions
====================

These are instructions to upgrade from earlier IMP versions. Please backup your
existing data before running any of the steps described below. You can't use
the updated data with your old IMP version anymore.

Upgrading IMP is as easy as running::

   pear upgrade -a -B horde/imp

If you want to upgrade from an IMP version prior to 5.0, please follow
the instructions in INSTALL_ to install the most recent IMP version
using the PEAR installer.

After updating to a newer IMP version, you **always** need to update
configurations and database schemes. Log in as an administrator, go to
Administration => Configuration and update anything that's highlighted as
outdated.


Upgrading IMP From 5.x To 6.x
=============================

The basic view now requires javascript support on the browser. If not
available, the user will automatically be redirected to the minimal view.


Server Options (backends.php)
-----------------------------

The 'namespace' option now requires the namespaces to be in the UTF-8 charset,
not UTF7-IMAP.

The 'smtphost' and 'smtpport' options have been removed. They have been
replaced by the 'smtp' option, which allows ALL available SMTP configuration
options to be overriden.

The 'admin' option has been changed: optional configuration parameters should
live within the base 'admin' array rather than a 'params' array within the
base.


Configuration Options (conf.php)
--------------------------------

The $conf['fixed_folders'] option now requires the mailboxes to be in the
UTF-8 charset, not UTF7-IMAP.

The $conf['compose']['link_attach_size_limit'] option was added.

The $conf['print']['add_printedby'] option was removed and replaced by the
'add_printedby' preference.

The $conf['user']['select_sentmail_folder'] option was removed. To prevent
changing the sentmail mailbox, the 'sent_mail_folder' preference should be
locked instead.

The following configuration options were removed::

   $conf['dimp']['viewport']['buffer_pages']
   $conf['dimp']['viewport']['viewport_wait']


MIME Viewer Options (mime_drivers.php)
--------------------------------------

The 'safe_addrs' option has been removed from the Images driver config.
To set the default list of e-mail addresses that should be considered "safe",
the 'image_replacement_addrs' preference can now be used.


Hooks (hooks.php)
-----------------

The 'mbox_sort' and 'mbox_special' hooks have been added.

The 'dimp_addressformatting' hook has been removed.

The $action parameter for reporting not spam message to the 'spam_email' and
'post_spam' hooks has been changed from 'ham' to 'innocent'.


Preferences (prefs.php)
-----------------------

The default values for these preferences have been changed::

   drafts_folder
   sent_mail_folder
   spam_folder
   trash_folder

The following preferences are no longer used and may be safely removed from
your preference backend (only after all users have logged in - these
preferences MAY be used to automatically upgrade to new preferences when
a user logs into IMP 6 for the first time)::

   dimp_qsearch_field
   dimp_show_preview
   dimp_splitbar
   dimp_splitbar_vert
   dimp_toggle_headers
   dynamic_view
   image_addrbook
   move_ham_after_report
   sig_first
   stationery

The 'cursor_compose' preference removed the 'sig' option. Existing preferences
will automatically be converted to 'bottom'.

The 'save_attachments' preference removed the 'prompt_yes' and 'prompt_no'
options. Existing preferences will automatically be converted.

The 'add_printedby', 'image_replacement_addrs', 'reply_charset', and
'reply_strip_sig' preferences were added.

The 'forward_default' preference now contains the 'editasnew' option.


API Changes
-----------

  - copyMessages

    The $mailbox and $target parameters are now required to be UTF-8 strings.

  - createFolder

    This call has been removed (replaced with 'createMailbox').

  - deleteMessages

    The $mailbox parameter is now required to be a UTF-8 string.

  - flagMessages

    The $mailbox parameter is now required to be a UTF-8 string.

  - folderlist

    This call has been removed (replaced with 'mailboxList').

  - moveMessages

    The $mailbox and $target parameters are now required to be UTF-8 strings.

  - searchMailbox

    The $mailbox parameter is now required to be a UTF-8 string.



Upgrading IMP From 5.0.x To 5.0.22
==================================

Configuration (conf.php)
------------------------

The $conf['spam']['email_format'] and $conf['notspam']['email_format']
configuration options have been added.



Upgrading IMP From 5.0.x To 5.0.20
==================================

Preferences (prefs.php)
-----------------------

The 'delhide_trash' preference has been added.



Upgrading IMP From 5.0.x To 5.0.15
==================================

Preferences (prefs.php)
-----------------------

The 'delete_mark_seen' preference has been added.



Upgrading IMP From 5.0.x To 5.0.14
==================================

Preferences (prefs.php)
-----------------------

The 'reply_lang' preference has been added.



Upgrading IMP From 5.0.x To 5.0.12
==================================

MIME Viewer Options (mime_drivers.php)
--------------------------------------

The 'allthumbs' option has been removed from the HTML driver.  Image thumbnail
previews are now always shown if an image conversion utility is present on the
system.



Upgrading IMP From 5.0.x To 5.0.10
==================================

Configuration Options (conf.php)
--------------------------------

The 'allow_resume_all' option has been removed.  Only messages specifically
marked as drafts can be resumed; however, all messages are given the option
to "Edit As New".



Upgrading IMP From 4.x To 5.x
=============================

This is a non-exhaustive, quick explanation of what has changed between an IMP
4.x installation to IMP 5.x.


HTML GUI editor
---------------

IMP only supports the CKeditor javascript HTML rich text editor.  Xinha is no
longer supported.

Button configuration is now stored in the prefs value 'ckeditor_buttons'.


Server Options (backends.php; OLD servers.php)
----------------------------------------------

The format of servers.php has changed and has been renamed to backends.php.

The 'realm' option has been removed.  Altering usernames at runtime should
instead by accomplished by using Horde's 'authusername' and/or IMP's
'preauthenticate' hooks.


Configuration Options (conf.php)
--------------------------------

Configuration relating to displaying the terms of agreement, GnuPG, OpenSSL,
spellchecking, and login redirection have been moved to Horde.

The 'show_preview' option has been removed; enabling previews is now handled
by the 'show_preview' preference.

The 'allow_resume_all_in_drafts' option has been removed; all messages that
appear in the configured Drafts mailbox are now always allowed to be resumed.

The 'css_files' configuration option for the dynamic (dimp) display has been
removed.  Equivalent behavior can now be found in the Horde-wide 'cssfiles'
hook.

The 'max_from_chars' and 'max_subj_chars' configuration options for the
minimal (mimp) display have been removed.

The following configuration options have been removed::

   allow_receipts
   append_trailer
   cache_folders
   limit_factor
   prepend_header
   show_account_colors
   size_limit
   sort_limit


Preferences (prefs.php)
-----------------------

The 'sending_charset' and 'time_format' preferences have been moved to Horde.

The following preferences are no longer used and may be safely removed from
your preference backend::

   attachment_display
   auto_delete_drafts
   delete_attachments_monthly
   delete_sentmail_monthly
   dimp_login_view
   disposition_request_read
   disposition_send_mdn
   fckeditor_buttons
   fetchmail_link
   fetchmail_menu
   filter_on_sidebar
   forward_bodytext
   image_addrbook
   image_replacement
   nav_audio
   nav_expanded_sidebar
   nav_popup
   purge_sentmail
   purge_spam
   purge_trash
   use_vinbox
   use_vtrash
   vinbox_id
   vtrash_id


Hooks (hooks.php)
-----------------

The format of hooks.php has changed.  See horde/docs/UPGRADING for more
information.

The 'vinfo' hook has been removed.  Use Horde's 'authusername' and/or IMP's
'preauthenticate' hooks instead.

The 'msglist_format' hook has been removed.  X-Priority header handling is now
handled in the core IMP code.  Attachment icon display is now handled by the
'atc_flag' preference.  The 'msglist_flags' hook is now used to dynamically
set flags on messages.


Custom Message Headers (OLD header.php)
---------------------------------------

The header.php configuration file has been removed.  Setting custom headers
is now done in the 'pre_sent' hook.


Custom Message Trailers (OLD trailer.txt)
-----------------------------------------

The trailer.txt file has been removed.  Setting message trailers is now done
in the 'trailer' hook.


Fetchmail
---------

All code relating to fetchmail has been removed.


Flags
-----

The list of available IMAP Flags/Keywords is now configurable via the
'msgflags' preference.

The \Answered, \Deleted, and \Draft IMAP flags are no longer user settable
by default - these flags have special meanings and are automatically handled
by the various message action functions instead.


Menu
----

The dynamic view (DIMP) no longer supports the 'action' parameter located
in config/menu.php.


Portal
------

Portal rendering has been moved to Horde - config/portal.php is no longer
needed or used.



Upgrading IMP From 4.1.x To 4.2.x
=================================

This is a non-exhaustive, quick explanation of what has changed between an IMP
4.1.x installation to IMP 4.2.x.


SQL Backend
-----------

An SQL table has been added that can be used to track sent messages. This is
necessary to provide users with the "favourite recipients" address book, and
for message rate throttling.

Execute the provided SQL script to add the table to your database, e.g.::

   mysql --user=root --password=<MySQL-root-password> <db name> < scripts/sql/imp.sql


Unified IMAP Quota Driver
-------------------------

Separate quota drivers for Cyrus and Courier servers are no longer
necessary. These drivers have been replaced by a generic IMAP driver that
should also be suitable for other IMAP servers that support the QUOTA
extension. Update ``config/servers.php`` and change the 'quota' => 'driver'
setting to 'imap'.


Application Hooks
-----------------

All hooks that are specific to IMP have been moved from the
``horde/config/hooks.php`` file. Move your existing IMP Hooks from there to
``imp/config/hooks.php``.


User-Defined Mailbox Icons
--------------------------

The usage of the hook ``_imp_hook_mbox_icons()`` has changed.  If you use this
hook, make sure you change your implementation so it returns the correct
value.


Changed Preferences
-------------------

The default values for the mailbox preferences 'sent_mail_folder',
'drafts_folder', and 'trash_folder' have been changed and localized. Use the
old values to prohibit the creation of duplicate mailboxes for users that
didn't explicitly set the mailboxes in their preferences.

The following preferences are no longer used and may be safely removed from
your ``config/prefs.php`` file and your preferences backend::

   'auto_expand'
   'num_words'

The 'mail_hdr' preferences has been moved from the identities to a regular
preference. Existing user preferences are no longer used and have to be
re-created by the users.


New Message List Format Hook
----------------------------

The new hook ``_imp_hook_msglist_format()`` has been added which allows the
formatting of a message entry in the mailbox message list to be altered
at the time the list is created.  This hook has made the following
configuration options obsolete::

   $conf['mailbox']['show_attachments']
   $conf['mailbox']['show_xpriority']

If you wish to continue using the functionality previously provided by these
options, you should activate the msglist_format hook in ``config/conf.php``.
The sample hook contained in ``config/hooks.php`` contains the code necessary
to replicate the previous behavior.


Spell Checking
--------------

The ``pspell`` driver is no longer supported since it does not work with
HTML messages.  If using pspell, you must upgrade to aspell version 0.60+.


Javascript HTML Editor
----------------------

Support has been added for FCKeditor as an option for the javascript HTML
editor available on the compose page.  You must have Horde 3.2 or later
installed to use this editor.



Upgrading IMP From 4.0.x To 4.1.x
=================================

This is a non-exhaustive, quick explanation of what has changed between an IMP
4.0.x installation to IMP 4.1.x.


Automatic Namespace Detection
-----------------------------

The ``namespace``, ``hierarchies``, ``folders``, ``delimiter``, and
``dotfiles`` parameters were removed from ``config/servers.php``.  Namespaces
are now automatically configured pursuant to RFC 2342.

If using the UW IMAP daemon, you may notice a bunch of additional namespaces
that were not displayed before as well as the ability of the user to
view all files that live in their home directory via the folders screen.
Information on how to correct your IMAP server configuration can be found at

  http://wiki.horde.org/ImpUWIMAPNamespaces


User-Defined Headers
--------------------

The ``config/headers.txt`` file has been removed and replaced by
``config/headers.php``.  Any user-defined headers should be migrated to this
file.  The new file has the advantage of allowing any valid PHP expression
to be executed at run-time when generating the headers.  See the top of
the ``headers.php`` file for the new format required.


Removed Preferences
-------------------

The following preferences are no longer used and may be safely removed from
your ``config/prefs.php`` file and your preferences backend::

   'disposition_request_delivery'
   'wrap_width'


Virtual Folders
---------------

The format for saved Virtual Folders has changed.  To convert to the new
format you must run the script located at
``scripts/upgrades/convert_vfolders.php``.


.. _INSTALL: INSTALL
