Community » Applications » Turba
Upgrading Turba
Contact: | turba@lists.horde.org |
---|
Contents
1 General instructions
These are instructions to upgrade from earlier Turba versions. Please backup your existing data before running any of the steps described below. You can't use the updated data with your old Turba version anymore.
Upgrading Turba is as easy as running:
pear upgrade -a -B horde/turba
If you want to upgrade Turba with all binary dependencies, you need to remove the -B flag. Please note that this might also try to install PHP extensions through PECL that might need further configuration or activation in your PHP configuration:
pear upgrade -a horde/turba
If you want to upgrade to an alpha or beta version of Turba, you need to tell the PEAR installer to prefer non-stable package versions. Please note that this might also install pre-release 3rd-party PEAR packages:
pear -d preferred_state=alpha upgrade -a horde/turba
If you want to upgrade from a Turba version prior to 3.0, please follow the instructions in INSTALL to install the most recent Turba version using the PEAR installer.
After updating to a newer Turba 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.
2 Upgrading Turba from 4.1 to 4.2
2.1 Attribute Changes
- Categories have been replaced by Tags. As such, you must update any local source definitions and remove the "Category" attribute.
2.2 Configuration Options (conf.php)
The following options have been added:
$conf['tags']['enabled']
3 Upgrading Turba from 4.0 to 4.1
3.1 Attribute Changes
- The "instantMessenger" attribute has been replaced by the "imaddress", "imaddress2", and "imaddress3" attributes.
- The default SQL schema has been updated, as well as the out of the box field definitions for the 'localsql' source. You must execute the database migrations for Turba to ensure you have the latest schema.
4 Upgrading Turba from 3.x to 4.x
4.1 Attribute Changes
- The "gender" attribute sets values of (literally) "male" or "female" now, and no longer 0 or 1.
4.2 Preference Changes
- The "addressbooks" preference has been removed.
4.3 API Changes
search
The $sources, $fields, $matchBegin, $forceSource and $returnFields parameters have been removed and replaced by the $opts parameter.
Added a 'rfc822Return' option to return a Horde_Mail_Rfc822_List object instead of the search results array (which remains the default).
5 Upgrading Turba from 2.x to 3.x
Important
These upgrade instructions assume that you are upgrading from at least Turba 2.2. If you have an older version of Turba, you must upgrade to at least Turba 2.2 before attempting to install Turba 3.
5.1 Configuration files
The config/sources.php configuration file has been renamed to config/backends.php. The entry for defining the connection parameters for an SQL backend other than the default Horde backend has changed - see the 'params' -> 'sql' configuration value.
5.2 Hooks
The _turba_hook_encode_{attribute} hook has been moved to the 'encode_attribute' hook.
The _turba_hook_decode_{attribute} hook has been moved to the 'decode_attribute' hook.
7 Upgrading Turba from 2.2.1 to 2.3
7.1 Share Table Updates
Some fields in the SQL share driver tables have been changed. Execute the provided SQL script to update your database if you are using the native SQL share driver:
mysql --user=root --password=<MySQL-root-password> <db name> < scripts/upgrades/2.2.1_to_2.3.sql
7.2 New fields
Examples for a few new fields have been added to config/attributes.php.dist and config/sources.php.dist. These field require Horde 3.3 or later though, so they are disabled by default. If you update your attributes.php and sources.php files and are using a sufficiently recent Horde version, you may want to uncomment those examples. These are the photo, phototype, logo, logotype, pgpPublicKey and smimePublicKey fields.
8 Upgrading to Turba 2.2
These are notes on upgrading from Turba 2.1.x to Turba 2.2.x.
Important
These upgrade instructions assume that you are upgrading from at least Turba 2.1. If you have an older version of Turba, follow the upgrade steps described in Upgrading to Turba 2.1 first.
8.1 New Default Schema
The default database address book schema has been changed to better match other address book applications and to ease synchronization with those.
You can still use your old address book schema without any restrictions, but if you want to migrate existing address books to the new default scheme, you can use the provided upgrade script. This script assumes that you use the old default schema from Turba 2.1 and doesn't permanently change any data unless you edit it.
To run the script you have to open it in any text editor and change the three variables at the top of the script $db_user, $db_pass and $db_table to fit your current Turba installation. You can then run the script to see how the data //would// be changed:
php scripts/upgrades/2.1_to_2.2_sql_schema.php
If you are happy with the results, you can edit the script again and change the $for_real variable:
$for_real = true;
As always make sure you have a recent backup before running the script once more, this time the changes will be permanent. Don't forget to update your configuration files or to re-create them from the .php.dist examples.
A few advanced attribute definitions have been commented out in config/attributes.php by default because they require Horde 3.2 or later to be installed. If you have a sufficiently recent Horde version you can uncomment those lines in attributes.php.
As part of the new default schema, the various address fields have been split into individual fields (such as homeStreet, homeProvince etc...). If you still wish to display an individual composite address field (which will give you the map links) you must add a composite field (such as homeAddress). There is an example entry in the sources.php.dist file.
The new schema also uses the "phone" field type that has been introduced with Horde 3.2. If you still run earlier Horde versions, change the phone field types in attributes.php to anything that fits your needs, e.g "cellphone" or "text".
8.5 Application Hooks
All hooks that are specific to Turba have been moved from the horde/config/hooks.php file. Move your existing Turba Hooks from there to turba/config/hooks.php.
9 Upgrading to Turba 2.1
These are notes on upgrading from Turba 2.0.x to Turba 2.1.
Important
These upgrade instructions assume that you are upgrading from at least Turba 2.0. If you have an older version of Turba, get a copy of Turba 2.0 and follow the upgrade steps described there first.
9.1 Synchronization Support
Synchronization with SyncML capable devices is possible now if you have at least Horde 3.1. You need to create a History backend with horde/scripts/sql/horde_histories.sql to allow synchronization. You also need to create default history entries for existing contacts by running the script scripts/upgrades/create_default_histories.php.
9.2 New Hook Parameters
The _turba_hook_encode_{attribute} and _turba_hook_decode_{attribute} functions are now passed an additional parameter - the object that is being loaded/saved. This enables you to create more powerful custom hooks that build a field from several other field's values (the opposite of composite fields), or otherwise modify a value based on other properties of the object.