Latest revision as of 14:58, 23 March 2009

Introduction

As of Geeklog 1.6.0, the install script has a new option (in addition to "New Install" and "Upgrade"), called Migrate. You will use the migrate option when moving your Geeklog site from one webserver to another (e.g. when changing hosting services). Naturally, this will require changes in the configuration, e.g. paths and URLs. The install script handles all that for the Geeklog core functionality, but plugins will need to perform these changes too. That's what the PLG_migrate function is for.

The API

function PLG_migrate($type, $old_conf)

As usual, $type is the plugin type ('calendar', 'forum', ...). $old_conf contains a copy of the $_CONF with the values before the migration, i.e. paths and URLs of the old site.

The plugin will then have to implement a function

function plugin_migrate_foo($old_conf)

In that function, the plugin can update its configuration, as needed. It has access to the current $_CONF array (if declared global, as usual), so it can easily check the options that need to be updated.

There is also a convenience function that the plugin has access to which will update the site's URL in the database. That function takes a list of tables and field names which list text fields to be searched for the old URL. For example, for the Links plugin:

$tables = array(
    'linkcategories'    => 'cid, description',
    'links'             => 'lid, description, url',
    'linksubmission'    => 'lid, description, url'
);

This array lists the 3 tables to be updated (linkcategories, links, linksubmission). On the right side, you'll see the fields to be updated. Please note that the first field listes has to be the table's index (in the above example: cid = category ID, lid = link ID). The other fields are supposed to be text fields, i.e. of one of the various text types (VARCHAR, TEXT, MEDIUMTEXT, ...).

With this, you can then easily update your plugin's tables to point to the new URL:

if ($old_conf['site_url'] != $_CONF['site_url']) {
    INST_updateSiteUrl($old_conf['site_url'], $_CONF['site_url'], $tables);
}

Please note that the INST_updateSiteUrl function is only available inside the plugin's migrate function.

Migration + Upgrade

Since Geeklog's install script can also handle plugin upgrades, there may be cases where plugins will need to be both migrated and upgraded. In that case, PLG_migrate will be called first, i.e. migrate first, then upgrade.