Topics

Upgrade Script Format

An upgrade script extends the 'upgradescript' class which makes creating new ones an easy task.  Upgrade scripts are only run during the 'upgrade' process and then only if specified conditions exist.

Upgrade scripts are located in the /install/upgrades/ folder.  The following properties/methods comprise a standard upgrade script.

  • $from_version - is the earliest version number (string) this script would be applied against.  If not defined (sub-classed), it defaults to the parent value of never running.  This string value would be the earliest version this script would apply to...say when the issue was introduced.  If you want the script to run on ALL previous versions (including pre-release versions), set this value to '0.0.0'  This value MUST be set for the script to be available.
  • $to_version - the is the latest version number (string) the script would be applied against.  If not defined, it defaults to the parent value of always running, IF a valid $from_version is set.  This string value is the latest version this script would apply to...say when an issue was fixed.  If you fixed an issue in release v2.0.8, you would set this value to '2.0.8'
  • name() - returns the name of the script for the upgrade screens.
  • description() - returns a longer description, where the default value is a variation of the script 'name'.
  • $optional - boolean value; 'false' indicates the script is always run, 'true' if the admin is given the option to run the script.  If the script will make significant changes to the system, you may want to make the script optional if it will NOT interfere with the system if it is NOT run.
  • checkVersion($version) - a routine to check the current database version number, $version (object).  The default (super-class) routine performs a basic version check and will return 'true' (or run the script) if the current system version is equal to, or between the $from_version and $to_version, but can be more complex if needed.
  • needed() - an additional routine to check if the script is even needed.  This value MUST return true for the script to run.  By default, the super-class returns false.  Unless a script contains a valid needed() method, it is DISABLED.  In a practical sense, the checkVersion() and needed() methods are redundant, but are intended to contain a logical function where the version alone is checked in checkVersion() and additional checks such as files or database tables existing/not existing are performed in the needed() method.
  • upgrade() - the main upgrade function run during an upgrade if BOTH checkVersion() and needed() return true.  This is the meat of an upgrade script.  It should print out or return a text phrase with the results of the upgrade.
Loading Help