Plugin Install / De-install Functionality

Purpose: Plugins require an install/de-install program to be located in the admin/plugins/{plugin name} directory. The program install.php should be able to handle the install and de-install of the plugin. Here you will find an overview of this code function and the overall relationship to the other plugin code.

The plugin install requires the Geeklog site administrator to first uncompress the plugin archive and then copy (move) the admin and public related directory and files to their respective public_html and admin/plugins directories. Once the files are in place and permissions checked, the install.php for the plugin is executed to install the plugin.

The files under the admin directory will include:

• install.php: This is responsible for creating all database tables, creating security and access feature records, registering the plugin. It needs to have full error recovery and be able to back-out any updates in case of incomplete install. It should be able to be restarted and handle being called more then once. The De-Install functions or routines will also be called by the Plugin Editor or Plugin Manager screen if the Geeklog Admin uses the Delete operation when viewing the Plugin details. The Delete functions should therefore be in the main plugin functions.inc for this reason. See the section on functions.inc for more informtion on the exact API for this funciton.
• upgrade.php: Any plugin related upgrade steps should be scripted and included here. This would primarily include any SQL changes. You may want to include the plugin version this upgrade is for in the program name - as in upgrade_v1.php. Regardless, the plugin install documentation should include details on how to upgrade if this is relevant.
• index.php: This is the main program that will be called for any plugin administration. This may include: Plugin configuration, Feature Management, Security Management or other administrative functions. This code would not normally be accessed by standard users. Some plugins may not have admin related code and others may have significant admin functions.

Your admin page(s) will be in http://yourgeeklogdomain/admin/plugins/{plugin name}/

Creating Install.php:

Developer notes:

• Include a permissions check at the top of this program to ensure the user has administrative rights
• Use standard function names like: plugin_createtables_pluginname()
• Include output debugging of install and de-install trace
• Trap errors after SQL statements and handle errors
• Include error handling to be able to back-out any SQL changes or install steps should there be an error and allow install script to be executed more then once if necessary without creating extra records or getting confused
• Create any default data for user that your plugin may need to be operational or will provide examples. Examples are plugin defaults, samples, pre-defined block definitions, pre-defined security settings etc.
• Provide user output of successful or un-successful completion with any error message.
• You may want to include a more descriptive successful message that outlines the next steps the installer (admin) should now do - such as final install or config steps.
• Your Uninstall function that will be located in functions.inc can be called from the Plugin Editor or the install program. The install program will call it upon error or when the user has called install when the plugin is already installed. In this case, the install program will prompt the user if they want to un-install the plugin.

Program overview

The following is an outline of the universal installer program structure. Refer to the example install.php for complete sample code for the actual function routines and logic.

1. Includes for any common functions or configuration variables
2. Call to SEC_inGroup('Root') to verify the user has administrative rights
3. The function plugin_install_pluginname() is the main plugin Install function. It is responsible for the following:
   • Create all new plugin tables
   • Create the plugin security groups. Generally there will be a new plugin user group (pluginname.user) and admin group (pluginname.edit) but you may have several other new groups to control access to your plugin features.
   • Create new plugin security rights. These are referred to as features. Features are assigned to groups and users. An example is that with Geeklog 1.3.6 a new feature was added called story.submit. This feature is granted to users and groups that you want to be able to submit stories directly and feature story.moderate would be required for users to approve general submitted stories and story.edit to be able to edit stories.
     Your plugin will likely have a plugin.edit and plugin.user feature. Example: The FileMgmt plugin has three features defined filemgmt.user, filemgmt.edit and filemgmt.upload.
     Your plugin needs to create a new record in gl_features for each new feature - access right.
   • Assign all the new features to the root group so the administrator by default will have full access to the plugin once the install is completed
   • Assign the related features to your new plugin groups. Example: the plugin.user feature needs to be assigned to the plugin user group.
   • Register the plugin - update the gl_plugins table. Check if plugin record already exits and if so remove it and then create a new record. This is just a clean way of ensuring duplicate plugin records are not created. The program should not get this far unless all subsequent install steps were completed successfully.
   • Return a successful install completion
4. The main code section first checks to see if it is being called from the install form and if so why - is user trying to install or uninstall. If this not a form process request - $action is not set - then determine if the plugin is installed or not. Depending on result - setup the form and post it to the user to get their input (install or to uninstall the plugin).

Plugin Uninstall

The function plugin_uninstall_pluginname() is called from the plugin install program under two conditions, the first being when there has been an error in one of the install steps. The second condition is that the install program has determined the plugin is already installed and presented the user with the option to delete the plugin. Under the first condition, you want to have all your plugin install procedures deleted and removed. The uninstall function should be written to completely back out or delete all plugin and security definition in the core plugin tables and then remove the plugin specific tables.

The uninstall function is also called by the PluginAPI remove() function which is called when the Plugin Editor Delete is used. The plugin editor will prompt the user to confirm that they really want to proceed and the user has to select Delete twice. In this case and in the case of undelete being called if there is an install error, you want the undelete function to proceed without any further checks.

The uninstall function is also called when the user runs the install.php after the plugin is installed and they select delete. The user could possibly execute the install and accidentally call the uninstall function. In this case, it would be good to have some form of confirmation. If the uninstall function is being called in this situation, the universal installer program will pass a value to the uninstall function. Example: plugin_uninstall_chatterblock('checkifenabled'). The uninstall function should be written to accept a variable but default it to blank if nothing passed. This is the only case where it is passed a value - check for a value in the uninstall function and if set then verify the Plugin is first not enabled. If it's a disabled plugin, then proceed and delete it - otherwise display a warning message and stop. Refer to the sample uninstall function for more details.

FAQ

1. What does enable/disable do in the Plugin Editor?

At the end of the lib-common.php, there is a call to all currently enabled plugins. For all enabled plugins, the associated functions.inc file is included. So enables/disables the controls whether the plugins functions.inc file is included. At the top of each plugins functions.inc are several more includes which will include the plugins config.php file and language file.

2. I've disabled the plugin and now I can't delete it

Once you have disabled the plugin, it functions.inc file is not included and the API call to the uninstall function returns as if the function did not exist. This one catches folks often. The plugin must be enabled

3. I don't see the phpblock function in lib-custom for this plugin

The developer can include his Block functions in the plugins functions.inc file. Since all enabled plugins have their associated functions loaded - the block function is made available and can be called from an GL core module or even another plugin.