File/program/lib/updatelib.php

Description

/program/lib/updatelib.php - update wizard

This file handles all system updates. The basic idea is as follows.

We assume that a previous version of Website@School is/was already correctly installed using the code in /program/install.php. Using this version the school has added many, many hours of work in entering data.

Now a new version is installed, i.e. the new files (or just the updated files) are copied/uploaded to the webserver, including the file version.php and perhaps also updated versions of modules, themes, etc. This yields an error message for visitors (the infamous 'error 050') because the database version and the file version no longer match. The user logging in into admin.php is forced to attend to the job 'update', arriving here in job_update().

There an overview is presented of the core version and versions of all subsystems, with the option to upgrade those that qualify. The actual work for the core version is done in update_core() in this file. The actual work for modules and themes are done via the code in those subsystems. However, these are called from here.

The user is more or less _forced_ to perform the upgrade: all ways lead to job_upgrade() while the internal (database) version does not match the file version.

The upgrade should perform all necessary steps to upgrade, ending with updating the internal version number to match the file version. After that the error message '050' for visitors is gone, and admin.php no longer forces the user to come here. It is possible, however, to manually arrive here to check the updates of modules, themes, etc. but I consider that less importent. That is: an upgrade of a module or theme will NOT be forced upon the user. It is wise, though to upgrade, but that is up to the user.

Constants
TASK_UPDATE_CORE = core (line 64)
TASK_UPDATE_MODULE = module (line 65)
TASK_UPDATE_OVERVIEW = overview (line 63)
TASK_UPDATE_THEME = theme (line 66)
Functions
job_update (line 93)

main entry point for update wizard (called from /program/main_admin.php)

This routine takes care of executing update routines for both the core program and modeles, themes, etc. It is called automagically whenever the core program version in the database is different from the version in the file {@lnk version.php} (see also main_admin()).

It can also be called manually via 'job=update'. When no specific task is specified, this routine shows the overview of versions for core, modules, themes, etc. Whenever a component is NOT up to date, an [Update] button is displayed. If a component IS up to date, we simply display the word 'OK'. This implies that when everything is up to date, the overview simply displays a list of OK's and the user is 'free to go'.

The actual updates for modules, themes, etc. is done via the various subsystems themselves, e.g. by calling htmlpage_upgrade() in the file /program/modules/htmlpage/htmlpage_install.php. The updates for the core program are actually performed from this file right here, see below for an example.

  • return: results are returned as output in $output
void job_update (object &$output)
  • object &$output: collects the html output
show_update_overview (line 139)

display an introductory text for update + status overview

  • return: results are returned as output in $output
void show_update_overview (object &$output)
  • object &$output: collects the html output
update_core (line 428)

update the core version in the database to the version in the version.php file (the 'manifest' version)

  • return: results are returned as output in $output
void update_core (object &$output)
  • object &$output: collects the html output
update_core_2010120800 (line 448)

perform actual update to version 2010120800

  • return: TRUE on success, FALSE otherwise
bool update_core_2010120800 (object &$output)
  • object &$output: collects the html output
update_core_2010122100 (line 466)

perform actual update to version 2010122100

  • return: TRUE on success, FALSE otherwise
bool update_core_2010122100 (object &$output)
  • object &$output: collects the html output
update_core_2011020100 (line 484)

perform actual update to version 2011020100

  • return: TRUE on success, FALSE otherwise
bool update_core_2011020100 (object &$output)
  • object &$output: collects the html output
update_core_version (line 261)

record the specified version number in the config table AND in $CFG->version

This utility routine records the new version number in the config table and also adjusts the version number already in core (in $CFG->version).

  • return: TRUE on success, FALSE otherwise
bool update_core_version (object &$output, int $version)
  • object &$output: collects the html output
  • int $version: the new version number to store in config table
update_module (line 292)

call the module-specific upgrade routine

this routine tries to execute the correct upgrade script/function for module $module_id. If all goes well, a success message is written to $output (and the update is performed), otherwise an error message is written to $output Either way the event is logged via logger().

Note that we take care not to load spurious files and execute non-existing functions. However, at some point we do have to have some trust in the file system...

  • return: results are returned as output in $output
void update_module (object &$output, int $module_id)
  • object &$output: collects the html output
  • int $module_id: primary key for module record in modules table in database
update_status_update (line 239)

return an anchor tag with link to the specific update function

This utility routine returns a ready to user HTML anchor tag.

  • return: ready to use HTML-code
array update_status_update ([string $task = NULL], [int|null $id = NULL])
  • string $task: which update task do we need to do?
  • int|null $id: which module/theme/etc. (NULL for core)
update_theme (line 364)

call the theme-specific upgrade routine

this routine tries to execute the correct upgrade script/function for theme $theme_id. If all goes well, a success message is written to $output (and the update is performed), otherwise an error message is written to $output Either way the event is logged via logger().

Note that we take care not to load spurious files and execute non-existing functions. However, at some point we do have to have some trust in the file system...

  • return: results are returned as output in $output
void update_theme (object &$output, int $theme_id)
  • object &$output: collects the html output
  • int $theme_id: primary key for theme record in themes table in database

Documentation generated on Tue, 1 Feb 2011 16:55:41 +0100 by phpDocumentor 1.4.0