#155 OnUpdate/OnUninstall/OnInstall functionality

Jan Pedersen
Core (214)

Current functionality for these three callback
functions required by module developers is extremely
limited, notwithstanding bugs in their operation. A
number of enhancements are required to make them useful
(and therefore useable.)

1/ Success and Failure messages must be settable to
overide the default xoops_module_on<function>_<dirname>

2/ Failure of the callback function must fail the
entire process and roll it back if neccessary (not sure
this is possible but see 3)

3/ The function templates should be changed to include
a $processState which indicates where in the parent
install/update/uninstall process the callback function
is being called. The callback should be called twice,
once before the main parent process starts and once
after it finishes. On the pre process call
$processState = 'Start'. On the post process call
$processState = 'End'. If the return from the callback
function when $processState = 'Start' is False, then
the entire parent process should be stopped and failed.
This allows the module devloper to check that certain
conditions exist before carrying out a process. The
$processState parameter can carry a third value,
'Rollback'. If the callback function receives this
state, then it can undo any work it might have done in
a previous call. Thus a template onInstall function
might look like;

function xoops_module_oninstall_dirname($module,
$processState) {
switch ($processState) {
case 'Start' : //Check that widget module is installed
case 'End' : //assume all ok so far so add some data
case 'Rollback' : //something failed so remove any
data that may have been added

Obviously the parent Xoops module install process needs
to be altered to use the callback function at the
appropriatre points in its cycle.


  • Jan Pedersen
    Jan Pedersen

    Logged In: YES

    1) this is possible

    2) You may have a point in this, that if the onUpdate
    function fails, it should not show the module as updated to
    the new version as it may not have updated important
    settings that will not be caught in future updates as the
    version number was updated.

    3) I am not sure whether that is directly connected to 2)
    but you want a function call at the beginning of e.g. the
    update process as well as at the end? Can you give examples
    of when this would be useful?

  • Ashley

    Logged In: YES

    1/ I am aware of setting error messages for failure in
    onUpdate but not success or failure in this or onInstall and

    2/ Yes.

    3/ Example for onInstall; $processState = "Start"
    Before installing a module, we might need to check that
    another module is installed (I have a requirement for this
    now btw.) If not installed, then entire install process
    should fail.
    $processState = "End"
    Add data to another module's tables.

    Example for onUpdate; $processState = "Start"
    Before updating, check that any modules it depends on are at
    right version level.
    $processState = "End"
    Assume that update process to date is OK and add new columns
    to a module table.

    Example for onDelete; $processState = "End"
    Remove data from another module's tables put in there during
    the install process.

    Hope that helps clarify requirement

  • Jan Pedersen
    Jan Pedersen

    Logged In: YES

    1) return false; or return true;

    2) I'll look into this

    3) Can you find other situations? Dependencies will become
    more critical in XooSphere due to the pluggable nature
    there, so perhaps we should rather have a dependency
    specification in xoops_version.php or similarly thought into
    the design.

  • Ashley

    Logged In: YES

    1/ point about messages is that I can only see a way of
    doing it (from the documentation that I've been able to
    find) for failure in onUpdate. You don't appear to be able
    to set messages for failure or success in any of teh other
    callbacks or success in onUpdate.

    3/ I could if I thought about it long enough :-) Point is
    that the requirement exists and is real, and will become
    more real as developers latch on to the fact that they can
    program into the three processes via the callbacks. I
    haven't a clue what xooSphere is. You've lost me there I'm

    When I've coded something like this before for financial
    systems upgrades, you simply ensure that progress is not
    available after a failure of a sub module. You already know
    how to rollback as you have unInstall functionality. Any
    mod developer using the callback functionality simply needs
    to ensure that they include rollback capability in their
    callback function. The main program block for an install
    would look perhaps something like;

    //Assume that callback function exist for brevity
    if (module->onInstall_Callback(_START)) then
    if (module->generic_install()) then
    if (module->oninstall_Callback(_END)) then
    return true; //everything ok
    return false //something failed

  • Jan Pedersen
    Jan Pedersen

    Logged In: YES

    1) Yeah, seems you are right. Will take a look at the entire
    module installation/update/uninstallation procedures in
    XOOPS 2.1.0

    3) Darn - had a long reply to this, then took a look at the
    module installation/update/uninstallation procedures and
    found another case where this is useful:
    When we update the XOOPS core from 1.3 to 2, we will need
    to change the database layout before the structure of core
    tables are as we want them to be.

    I will definitely put your suggestion in XOOPS 2.1.0, but
    still hold the opinion that dependencies in particular
    should be handled in the core by some standardised method.

  • Ashley

    Logged In: YES


    What happened to this?