Upgrading Instructions

Upgrading requires replacing a few files, and sometimes updating your configuration. You can upgrade from a previous version of Datamapper ORM, from DMZ, or the original DataMapper.

All versions

Overwrite application/libraries/datamapper.php.
Copy any new extensions in application/datamapper that you would like to use.

Some extensions may require additional views, libraries, helpers, or other items to function correctly. Please check the extensions you plan on using.
If you are using the Production Cache, please clear it, and possibly even disable it until you have tested the new version.

Then look below for additional, specific changes for each version.

Upgrading from a previous version of DataMapper ORM

You can determine which version of Datamapper ORM you are using by looking at the top of application/libraries/datamapper.php

From 1.8.1 to 1.8.2

DataMapper 1.8.2 is mainly a bugfix release, altough it does add some new features. One important feature is support for CodeIgniter 2.0.3 and newer (including Reactor).

To use this version, you need to install the DataMapper bootstrap in your index.php file:

/*
 * --------------------------------------------------------------------
 * LOAD THE DATAMAPPER BOOTSTRAP FILE
 * -------------------------------------------------------------------- *
 */
require_once APPPATH.'third_party/datamapper/bootstrap.php';

Place this line of code at the end of your applications index.php file, just ABOVE the CodeIgniter bootstrap file!

DataMapper 1.8.2. only works on CodeIgniter version 2.0.3. and above!

From 1.8.0 to 1.8.1

DataMapper 1.8.1 is mainly a bugfix release, altough it does add some new features. There are no additional upgrade instructions for this release.
DataMapper 1.8.1. only works on CodeIgniter version 2.0.2. and below!

Upgrading from Datamapper DMZ "OverZealous" Edition

From 1.7.1 to 1.8.0

DataMapper 1.8.0 is mainly a bugfix release, altough it does add some new features. There are no additional upgrade instructions for this release.

From 1.7.0 to 1.7.1

Make sure you replace all extensions, since they now work with get_iterated!
If you had previously overridden _assign_libraries, you will need to override _dmz_assign_libraries instead.
Make sure you check out the new When To Use Get Iterated section for getting the most out of Datamapper ORM 1.7.

From 1.6.2 to 1.7.0

Replace application/helpers/inflector_helper with the updated version in Datamapper ORM.
If you want to use the new localization functionality, you need to add lang_file_format to your config file.
A minor "gotchya" with the new localization (even if it is not explicitly enabled) is that you may find that relationships have a $validation entry when they didn't before. (This occurs when there is a language key of the form ${model}_${relationship}.)
If this causes an issue, you can forcibly disable localization by setting the config option field_label_lang_format to something nonsensical, like 'DO_NOT_USE_LOCALIZATION'.
It is recommended, but optional, that you modify your CodeIgniter installation to improve compatibility.
Many methods and variables have been made private or protected. You will get class errors if you have overloaded these in the past. Some of the private variables have also been renamed.

These new reserved names have been added, and should not be overwritten:

New Functions
get_iterated	get_paged	get_paged_iterated	get_raw
count_distinct	result_count	{query}_field_func	_add_to_select_directly
localize_field	localize_by_model	_get_generated_timestamp
_clear_after_query	_handle_related	_process_special_query_clause
New Variables
$timestamp_format	$_dmz_config_defaults	$_field_tracking
$lang_file_format	$field_label_lang_format
Renamed Variables
$_instantiations	$_query_related	$_validated

As this is a significant update, you really should look at the Change Log, to see how the new features can benefit you.

From 1.6.1 to 1.6.2

Bugfix release, no changes necessary.

From 1.6.0 to 1.6.1

If you used the example application/config/datamapper.php configuration file, change the value of $db_params from NULL to ''.

From 1.5.4 to 1.6.0

Due to the new DB mapping, you may experience errors with custom code that expected $this->db to be shared across models.

If you don't need subqueries or include_related_count, then you can set $db_params to FALSE and Datamapper ORM will revert to the shared DB.

Note, however, that other changes have been made that may cause issues with a shared DB class.

These new reserved names have been added, and should not be overwritten:

Functions
func	get_sql	include_related_count	{query}_subquery
{query}_func	{query}_related_subquery	_process_function_arg	_parse_subquery_object
Variables
$db_params	$instantiations

As this is a significant update, you may want to look at the Change Log, to see how the new features can benefit you.

From 1.5.3 to 1.5.4

Bugfix release, no changes necessary.

From 1.5.2 to 1.5.3

If you were using the private method _to_object, it works completely differently now.

From 1.5.1 to 1.5.2

The default behavior for indexing the all array has been changed.

If you are getting duplicate results in your queries, you have two options:
1. Update your queries to include DISTINCT whenever possible. This is the recommended option.
2. There is a new config option, all_array_uses_ids. Set this to TRUE to restore the original behavior.

From 1.4.x to 1.5.1

Two of the extensions have been renamed, due to the new extension prefix support.
I highly recommend you update your code, because the old names are no longer be supported.

You will need to replace all instances of 'arrayutils' with 'array', and 'csvutils' with 'csv'.
Replace all of the included extensions, and remove the old arrayutils.php and csvutils.php.

Older Upgrades

You can find upgrade instructions for older versions by downloading a previous version of DataMapper. Version 1.6.2 contains all of the upgrades through 1.6.2.

Upgrading from the original DataMapper

If you are upgrading from the original DataMapper, these are the steps you should take.

Update your application/config/datamapper.php file, as there are a few new items.
Overwrite application/libraries/datamapper.php.
Overwrite application/language/english/datamapper.php.
Optionally, upload the application/datamapper directory to your CodeIgniter application folder, to enable the use of extensions.
Look over the upgrade information above, to see if you are using any hacks or tricks that may be broken by Datamapper ORM's new features.
After reading through this manual, you may want to adopt many of the new features throughout your code!