Difference between revisions of "Patches and Upgrades"

Revision as of 20:10, 9 August 2009

Introduction

The repository allows a way to have patches or upgrades to existing plugins offered for one-click automatic installation via. the repository. However, there is a certain file format that must be followed for patches and upgrades.

Since the act of patching and upgrading are almost the same (Both add/edit/remove files and / or SQL), the only difference is that an upgrade updates your plugin version number as well. Hence the structure of both are identical.

In the root directory of the patch / upgrade, there has to be the following directories and files:

• admin - This folder holds the files that you would like to be moved to the public_html/admin/plugins/yourplugin folder. Files with the same name will overwrite existing ones.

• public_html - All files that you would like copied to /public_html/yourplugin folder.

• plugins - All files you would like to be copied to /plugins/yourplugin folder.

• updates.php -- See below for information on this file

UPDATES.PHP

This file contains the instructions for the update / upgrade process to follow. This file is mandatory, and without it your patches / upgrades will not be able to be offered for automatic one-click install, instead will have to be manually installed by the user.

The structure of the file is as follows:

The file MUST include a static class named UpdatePlugin, that implements the PluginUpdateInterface interface.

PluginUpdateInterface interface:

interface PluginUpdateInterface
{
    public static function init();
}

The sample class is below, with explanations:

class UpdatePlugin implements PluginUpdateInterface
{
    public static $_SQL_DATA = array();
    public static $_SQL_PTABLES = array();
    public static $PLUGIN_NAME = 'repositorylisting';
	
    public static function init()
    {
        // do nothing
        return true;
    }


}

• public static $_SQL_DATA - This is an array of SQL files, that is any SQL you would like to be executed as part of the update / upgrade.

• public static $_SQL_PTABLES - This is an array of all tables that your plugin currently has assigned to it in the Geeklog database. This is for backup purposes, as all plugin data is backed up before an update / upgrade, in case of corruption to avoid data loss.

• public static $PLUGIN_NAME- This is the name of the plugin that it goes by in the plugin table.

• public static boolean function init(); This function must return either true or false. False indicates a serious error occurred and the update must be terminated. This function allows you to include any code you want to execute during the update / upgrade. UpdatePlugin::init() is called after everything has been performed (SQL and file moves), before cleanup happens.

This cannot be stressed enough - you MUST return TRUE or the installation of your update / upgrade will be terminated, and the changes rolled back. Hence do NOT return false for some tiny warning, unless it is serious enough to cancel installation. In this regard, this function is really only for adding new configuration values, removing old ones, and so on. This is not for any SQL or FILE MOVE operations - allow the built in functions do that work more efficiently and with corruption protection.

How it works

Once an upgrade or a patch has been uploaded into the repository, if it is a patch, it is assigned a unique patch id for that plugin. If it is an upgrade, all it needs is the old version it is replacing. This is important. While patches can be made to work with any Plugin version, Upgrades will ONLY upgrade from the 'old plugin version' specified on upgrade upload. This is a security feature to prevent security holes where code is thought to be there, however since it is an old version, the code is missing and the plugin crashes or has vulnerabilities. With patches, this is not so much an issue, as upgrades will always include any fixes that have been issued as patches.

Once the client clicks 'Check for Updates', a check is performed against every repository in their repository database, and any updates / upgrades are returned. The user may then select which ones they wish to install, and they will install / or fail without affecting any other updates.