phpWebSite developer documentation :
Module Installer feature API
Content
- What does the Module Installer feature is
- How it works
- Understanding how to create compliant modules
- Final notes
top of page
What does the Module Installer feature is
Module Installer (hereinafter indicated as M.I.) is a feature introduced in phpWebSite 0.8.1-CVS which allows installation/removal of modules to be automated and controlled by the Admin Panel; it had been created by Philip McAllister and extended to its actual form by Alessandro Pisani and Jeremy Agee.
top of page
How it works
When called, the M.I. accomplish the following steps :
- scan of the mod/ sub-directory of the phpWebSite installation to find out currently installed modules (non-installable core modules such as mainpage,userpage,poll,blocks,... will be automatically excluded by the harvest)
- scan each of the modules found for proper install and uninstall capabilities
- generate the resulting list and display it onto the panel
During phase 2, the M.I. will look for :
- install capability:
- modulename_setup.php
- modulename_install.php
- index.php
- uninstall capability:
- modulename_uninstall.php
- index.php
In cases (a) , (b) for the install capability and (a) for the uninstall capabilityno more testing is performed, except for those core modules which require them
(i.e. the Calendar, for which M.I. contains a work-around to allow upgrade for users coming from a phpWebSite 0.7.x-to-0.8.x upgrade).
The resulting URL entry in the panel will be:
<a href="./mod/modulesname/module_xxxxx.php">text</a>
where xxxxx can be "setup" or "install", as seen above.
In cases (c) for the install capability and (b) for the uninstall capability file /mod/modulename/index.php is searched for one of :
- case "xxxxxx": entry in the switch($op) construct (where xxxxxx can be "install" or "uninstall").
- if( $op == "xxxxxx" ) entry (where xxxxxx can be "install" or "uninstall").
If found, the resulting entry in the panel will be:
<a href="./mod.php?mod=$file&op=xxxxxxx">text</a>
where xxxxx can be "setup" or "install", as seen above.
Please note that is also possible to create an hybrid installation method having modulename_install.php and the index.php?op=install binding at the same time (currently this is used by Hub-It and Comments modules).
top of page
Understanding how to create compliant modules
When creating new modules, making them compliant to the M.I. could benefit both sites-admins and users. Below are the conventional rules to create M.I.-compliant modules.
- Creating separate modulename_install.php and modulesname_uninstall.php files is preferred instead of usage of index.php. This is because modulesname_install/uninstall can be easily and cleanly called also by the phpWebSite install/upgrade scripts located in /setup. This way also make code maintenance easier
- Usage of modulename_install.php instead of modulename_setup.php is preferred: modulename_setup.php is the old syntax (pre-M.I.) and it is allowed mainly for backward-compatibility
- Important : to avoid the M.I. to report your module as "not yet installed" also when already installed you need to add an entry to the modules table in the install phase like:
$result = mysql_query("INSERT INTO " . $table_prefix."modules VALUES ( '', 'ModuleLabel', 'mod.php?mod=moduledir', 'moduleicon.png', 'moduledir', '0', 'modulename_block.php', '0', '0', 'adminmenu', 'ModuleName x.y - written by Author')");
- Providing the uninstall capability is not actually mandatory, btw it is considered a desiderable feature
- Security : If you're provinding modulesname_install.php/uninstall.php for your module, you also need to secure them, to make sure users can't call them directly via browser (i.e. opening http://www.yoursite.ext/mod/modulesname/modulesname_install.php in the browser).
This can be done creating modulename_install.php/uninstall.php in this way:
/* security check */
global $PHP_SELF;
if(substr_count($PHP_SELF,"/mod/")) $inc_prefix="../../";
else if(substr_count($PHP_SELF,"mod.php") || substr_count($PHP_SELF,"admin.php")) $inc_prefix="./";
else $inc_prefix="../";
include_once($inc_prefix."modsecurity.php");
include($inc_prefix."config.php");
if(!check_internal_call())
html_header_location("$phpws_url");
/* end security check */
...install code...
top of page
Final notes
Dear Developer/Admin:
This is the first incarnation of the M.I.; we hope you'll find it useful and easy to deal with. If you notice a bug, or you want to suggest improvements and enhancements please contact us: your help is always welcome.
<signed>
The phpWebSite Development Team
Alessandro Pisani <alextxm@users.sourceforge.net>