Upgrade Functions

As a plugin evolves it is not uncommon for a developer to want to change a fundamental way a plugin stores its data. If the developer cares about backwards compatibility (and we all do right?) then they will often need to have some way to help transition users in a completely seamless manner to the new scheme.

Movable Type facilitates this process through the use of upgrade functions. Upgrade functions are registered for a specific object class (like “entry,” “page” or “author”). Then for each record associated with that class, Movable Type will pass that record to a function for tweaking and modification. Upgrade functions are also associated with a specific schema version, that way Movable Type is ensured only to run the function for those users for which the upgrade function is relevant, and only against a specific version of the schema.

Developers can also register raw SQL code to be run against the database if that is easier.

name: Example Plugin for Movable Type
id: Example
description: This plugin is an example plugin for Movable Type.
version: 1.2
schema_version: 10
upgrade_functions:
    my_function:
        version_limit: 9
        priority: 1
        updater:
            type: entry
            label: "Doing something to all entries."
            condition: $Example::Example::Plugin::my_upgrade_condition
            code: $Example::Example::Plugin::my_upgrade_function
            sql: $Example::Example::Plugin::my_upgrade_sql

Upgrade Function Registry Properties

• version_limit - the schema version for which this upgrade function should be run against. For example, if a user is upgrading from schema version 5 to 6, then the version limit would be set to 5 indicating that the upgrade function should not be run if the current schema version is greater than 5.
• priority - this is used to determine the order in which a set of upgrade functions should be run. (1 has the highest priority ensure that it will be run first)

Updater Registery Properties

• type - the object class for which this upgrade function applies. This also determines the type of the object that will be passed into each of the related handlers.
• label - The text that is displayed to the administrator during the upgrade process to provide some insight into the operation being performed.
• condition - a handler that should return a boolean value, true if the associated upgrade handler should be run, and false otherwise.
• code - a reference to a handler to process each object in the system for which this upgrade function applies.
• sql - a reference to a hander that should return an array of SQL statements that should be run against the database.

Sample Plugin.pm File

Here is a sample set of handlers for each of the registry properties above.

package Example::Plugin;
use strict;

sub my_upgrade_function {
    my ($obj) = @_;
    $obj->some_property('some value');
}

sub my_upgrade_condition {
    my ($obj) = @_;
    return 0 if $obj->title eq "Foo"; # do not upgrade this record
    return 1; # upgrade this record
}

sub my_upgrade_sql {
    return (
      "UPDATE mt_entry SET some_property='xyz' WHERE title='Foo'",
      "UPDATE mt_entry SET some_property='123' WHERE title='Bar'",
    );
}

You should note that in the my_upgrade_function handler, as with all upgrade handlers, there is no need to issue a $obj->save() command with the corresponding object being upgraded. Movable Type will call the save() method on the object after all the upgrade functions associated with this schema version and this object type have been run.