Upgrade API

Introduction

If you have done the right thing, Moodle will automatically create the database tables for your plugin when you visite the Admin notifications page (.../admin/index.php). This process is controlled by three files within your plugin:

version.php

This records the version of the plugin code

db/install.xml

This is used when someone installs your plugin for the first time.

db/upgrade.php

This is used when someone who had an older version of your plugin installed upgrades to the latest version.

In addition, Moodle also stores in the database the currently installed version of each plugin. This is normally stored in the mdl_config table, in a row with name something like plugintype_pluginname_version. For example qtype_myqtype_version. The exception to this rule are modules and blocks. Installed module version numbers are stored in the mdl_modules table. Block version numbers are in mdl_block.

A specific example

For the rest of this document, I will use a particular example, becuase it should make the explanation easier. You should be able to see how to generalise it.

We will suppose you that you are making a new question type myqtype. This is plugin type qtype, and the code will be in the question/type/myqtype folder. The currently installed version number will be stored in the qtype_myqtype_version row of the mdl_config table.

In addition, we will just consider the first two releases of the plugin. The first release will have version number 2008080100, and will just use one database table mdl_question_myqtype, with two columns col1 and col2. Then we will suppose that the second release is 2008080200, and that requires an extra column, newcol, to be added to the mdl_question_myqtype table.

The files you need for the first release

version.php

$plugin->version  = 2008080100;
$plugin->requires = XXXXXXXXXX; // Copy the current value from the top-level version.php file.

db/install.xml

This file, which you should create with the XMLDB editor, should contain the definition for your mdl_question_myqtype table, with the two columns col1 and col2.

At this stage, you do not need a db/upgrade.php file.

The files you need for the second release

version.php

$plugin->version  = 2008080200;
$plugin->requires = XXXXXXXXXX; // Copy the current value from the top-level version.php file.

db/install.xml

This file should now contain the updated definition for your mdl_question_myqtype table, with three columns col1, col2 and newcol.

db/upgrade.php

This file should contain the code that people need to run to upgrade from version 2008080100 of your plugin. That is, the code to add a column newcol to the mdl_question_myqtype table. The upgrade.php file should contain a single function xmldb_qtype_myqtype_upgrade that looks a bit like:

function xmldb_qtype_myqtype_upgrade($oldversion = 0) {
    $result = true;

    /// Add a new column newcol to the mdl_question_myqtype
    if ($result && $oldversion < 2008080200) {
        // Code to add the column, generated by the 'View PHP Code' option of the XMLDB editor.
    }

    return $result;
}

What happens when a user installs or upgrades your plugin

The process is triggered when an administrator goes to the Admin notifications page (.../admin/index.php). The code that does the work is the upgrade_plugins function in lib/adminlib.php. In pseudo-code, what it does is:

For each plugin of this type (e.g. all qtype plugins) {
    // For the body of this loop, suppose the current plugin being processed is myqtype.

    Check that question/type/myqtype/version.php, .../db/upgrade.php and .../db/install.php exist.

    if ($CFG->qtype_myqtype_version exists, and is less than the number in version.php) {
        Call the upgrade function xmldb_qtype_myqtype_upgrade from
                upgrade.php, passing the old version number ($CFG->qtype_myqtype_version)
                which says what is currently installed
        Update $CFG->qtype_myqtype_version to the latest number from version.php
                to record what is currently installed
    }

    else if ($CFG->qtype_myqtype_version does not exist) {
        Create the tables from the definitions in install.xml
        Update $CFG->qtype_myqtype_version to the latest number from version.php
                to record what is currently installed
    }
}

Of course, it is a bit more complex that than. However, the code in the upgrade_plugins is quite clear, and I encourage you to go and have a look at it so you can see all the details of how it works. That is the best way to really understand what is happening.

Let us now look at some worked examples:

User installs version 2008080100 of myqtype

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

1. The user will unzip myqtype.zip into the question/type folder.
2. The user will visit the Admin notifications page.
3. This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

User upgrades from version 2008080100 to version 2008080200 of myqtype

To start with, the mdl_question_myqtype table will exist with the two columns col1 and col2; and the qtype_myqtype_version row in the mdl_config table will contain 2008080100.

1. The user will delete the old question/type/myqtype folder.
2. The user will unzip the new myqtype.zip into the question/type folder.
3. The user will visit the Admin notifications page.
4. This will trigger Moodle to search for plugings to upgrade. It will find that the code for version 2008080200 the qtype_myqtype plugin is now present, but the installed version of the the database tables (qtype_myqtype_version) is 2008080100. Therefore, it will call xmldb_qtype_myqtype_upgrade from upgrade.php, passing 2008080100 as the $oldversion argument.

At the end of this process, the mdl_question_myqtype table will now have three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

User installs version 2008080200 of myqtype into a clean Moodle install

To start with, the mdl_question_myqtype does not exist, and there will not be a qtype_myqtype_version row in the mdl_config table.

1. The user will unzip the 2008080200 version of myqtype.zip into the question/type folder.
2. The user will visit the Admin notifications page.
3. This will trigger Moodle to search for plugings to upgrade. It will find that the code for the qtype_myqtype plugin is now present, but there is no trace of it in the database, so it will install the plugin from the install.xml file.

At the end of this process, the mdl_question_myqtype table will exist with three columns col1, col2 and newcol; and the qtype_myqtype_version row in the mdl_config table will contain 2008080200.

Summary

The first time a user installs any version of your plugin, the install.xml file will be used to create all the required database tables. Therefore install.xml should always contain the definition of the up-to-date database structure. Moodle recognises this situation because there is a version.php file on disc, but there is no plugintype_pluginname_version value in the mdl_config table.

If the user already had a version of your plugin installed, and then upgrades to a newer version, Moodle will detect this because the version.php file will contain a newer version number than the plugintype_pluginname_version value in the mdl_config table. In this case, Moodle will run the code in the upgrade.php file, passing in the old version number, so that the correct bits of upgrade can be run, as controlled by the if ($oldversion < XXXXXXXXXX) blocks of code.

The contents of the install.xml and upgrade.php files should be generated using the XMLDB editor.

See also

• XMLDB_Documentation
• Coding guidelines
• DDL functions
• install.xml file documentation