Plugin install and upgrade

From e107 Wiki
Jump to: navigation, search

e107 Wiki: English | Русский | Deutsch | Français | Magyar | Português | Български | Česky | Nederlands | Ελληνικά | Italiano | Norske | Polska | Slovenščina | Español | Svenska | Translate: Wiki | Page

logo_wiki.png

Current Release 1.0.4 | e107.org | Download | Changelog | Forum | Plugins | Themes | RSS Feed of Latest Changes | Atom Feed of Latest Changes


How to write a plugin
Main page > I : First Aid > II : Development > III : Administration > IV : How To's > V : Plugin Writing > VI : Theming & Shortcodes


Contents

Plugin Installation, Uninstallation and Upgrading

Much of the information needed to manage installation and upgrading of plugins is simply defined in plugin.php.

However there are other things to consider, and other features of E107 which may be useful for a more complex installation.

Note: a plugin that requires no installation is one that:

  • has no admin pages
  • is not a module
  • has no database tables it needs to create
  • has no preferences to set
  • has no short codes
  • has no BB codes
  • has no integration into the main Admin pages Status or Latest areas


Relevant variables in plugin.php

( See plugin.php for more detail).

  • $eplug_done - Message to be displayed when your plugin has been successfully installed.
  • $eplug_upgrade_done - Message to be displayed when your plugin has been successfully upgraded.
  • $eplug_prefs - An associative array of your plugins preferences and their default values to be added when your plugin is installed. Preference names should be assigned a prefix to uniquely identify them with your plugin as they are stored globally.
  • $eplug_array_pref - Used for 'cumulative' preferences - where several plugins may each contribute a value.
  • $upgrade_add_prefs - Preferences to be added when the user upgrades your plugin.
  • $upgrade_add_array_pref - 'Array' or 'cumulative' preferences to be added when the user upgrades your plugin.
  • $upgrade_remove_prefs - Preferences to be removed when the user upgrades your plugin.
  • $upgrade_remove_array_pref - 'Array' or 'cumulative' preferences to be removed when the user upgrades your plugin.
  • $eplug_table_names - A string array of database tables created by your plugin. Does not required the e107 database prefix.
  • $eplug_tables - A string array containing the SQL used to create and, if required, populate your database tables when your plugin is installed. You need to use the e107 constant MPREFIX to prefix your table names.
  • $upgrade_alter_tables - A string array containing the SQL used to update your database tables when your plugin is upgraded. You need to use the e107 constant MPREFIX to prefix your table names.


Functions in plugin.php

Note: as the plugin.php file can be loaded multiple times for some admin pages (e.g. Plugin Manager) you should ensure that these functions cannot be declared multiple times. This can be done, for example, by wrapping the function declaration inside a function_exists() check.

myplugin_install()

Define the function myplugin_install(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed during the plugin's install.

This is useful as the plugin.php file is read on many occasions, so this prevents install only functionality from running when it shouldn't.

This function is run before any e107 plugin install processing is done.


myplugin_upgrade()

Define the function myplugin_upgrade(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed when the plugin is upgraded.

This is useful as the plugin.php file is read on many occassions, so this prevents upgrade only functionality from running when it shouldn't.

This function is run before any e107 plugin upgrade processing is done.


myplugin_uninstall()

Define the function myplugin_uninstall(), where myplugin is the name of the plugin's folder, in your plugin.php file and it will be executed when the plugin is uninstalled.

This is useful as the plugin.php file is read on many occassions, so this prevents uninstall only functionality from running when it shouldn't.

This function is run before any e107 plugin uninstall processing is done.


Optional Files

'Core' plugins can have a file called 'path_name_update_check.php' in the directory (where 'path_name' is the name of the plugin directory). This can contain code to assist with the installation and update process, where the functionality provided by the variable arrays isn't appropriate.

In 2.0.x this feature is extended to all plugins.

This module must, if present, provide two functions:

  • It must add an entry to the $dbupdatep[] array, whose index will be unique throughout all plugins and core functions (e.g. my_plugin_10_20). The value of the entry is to be a string which is displayed to the user while prompting for the upgrade.
  • It must provide a function, whose name is 'update_' prepended to the array index used for the corresponding entry in $dbupdatep[] - e.g.

function update_my_plugin_10_20($type=).

An example (from the forums) follows:

Code: Sample update routine
$dbupdatep['forum_07'] =  LAN_UPDATE_8." .617 forums ".LAN_UPDATE_9." .7 forums";
function update_forum_07($type='') 
{
// Routine does any checks required to determine whether an upgrade is necessary
// If $type == 'do' - actually does the upgrade
// Otherwise just does the checks, and returns:
//     TRUE - no upgrade required (all up to date)
//     FALSE - upgrade required
}

Any upgrade routine should be written such that it will handle a partially upgraded plugin; both to assist users who have used intermediate code versions from SVN, and to better handle failed upgrades.

If appropriate, the above principle could be extended to handle several levels of upgrade, by adding multiple entries to the $dbupdatep[] array, and by having multiple upgrade routines.

Checking for installed plugins

In 2.0 there is a new pref - $pref['plug_installed'][].

This can be used to check whether a plugin is installed, and the installed version, as described here


To add:

  • $plug variable