From KnowledgeTree Community

Contents 1 Upgrades 1.1 Files 1.2 upgrade.inc.php 1.3 UpgradeItems.inc.php 1.3.1 UpgradeItem class 1.3.1.1 Descriptor 1.3.1.2 Attributes 1.3.1.3 Methods 1.3.2 SQLUpgradeItem class 1.3.2.1 Methods 1.3.3 FunctionUpgradeItem class 1.3.3.1 Methods 1.3.4 RecordUpgradeItem class 1.3.4.1 Methods 1.4 UpgradeFunctions.inc.php 1.4.1 UpgradeFunctions class

Upgrades

Files

• lib/upgrades/upgrade.inc.php
• lib/upgrades/UpgradeItems.inc.php
• lib/upgrades/UpgradeFunctions.inc.php

upgrade.inc.php

upgrade.inc.php initialises the admin connection to the database, and provides functions to describe the upgrade process between two versions.

• setupAdminDatabase - sets up the admin database
• step_sort_func - A sort function used to sort the upgrades. Ensures the upgrade table is made first.
• describeUpgrade - generates a sorted list of upgrade item objects between two versions. Uses UpgradeItem's getUpgrades method to generate the items, and step_sort_func to sort them

UpgradeItems.inc.php

UpgradeItems.inc.php describes the UpgradeItems class and its derived classes - currently SQLUpgradeItem, FunctionUpgradeItem, and RecordUpgradeItem

UpgradeItem class

This class is an "abstract" class - nobody ever instantiates it. It provides the common behaviour between the other classes.

Descriptor

The descriptor is the unique identifier that describes a particular upgrade. This can be used to ensure that the same upgrade isn't done more than once.

Attributes

• type - a string which differentiates the types of upgrades
• name - the name of the upgrade
• version - Which version the upgrade applies to (1.2.3 means that 1.2.3 version includes this upgrade)
• description - human-readable description for the upgrades page
• phase - allows for the ordering of upgrades for the same version relative to each other
• parent - mostly unused - was to be used to group together upgrades with a particular RecordUpgradeItem to make it easier to see what actions were taken at a time
• date - set to the current date when the upgrade item is recorded in the upgrades table
• result - set to whether the upgrade item succeeded to record in the upgrades table.

Methods

• isAlreadyApplied - checks the upgrades table to see if this ugprade has already occurred
• performUpgrade - perform the upgrade, including recording the success. Generally, _performUpgrade is overridden.
• _performUpgrade - does the actual upgrade dirty work - separated so derived classes get the recording of the upgrade in performUpgrade
• getUpgrades - abstract, used to generate a list of upgrades of a particular type between two versions

SQLUpgradeItem class

This class describes an upgrade that is performed based on a file found in the sql/mysql/upgrade folder.

Methods

• getUpgrades - searches for files that represent upgrades between the two given versions
• _getDetailsFromFileName - gets the "from version", "to version", description, and phase of an upgrade based on a particular file
• _performUpgrade - Uses SQLFile::sqlFromFile to extract the SQL statements, and DBUtil::runQueries to execute them

FunctionUpgradeItem class

This class describes an upgrade that is performed based on functions defined in UpgradeFunctions.inc.php

Methods

• getUpgrades - Uses the 'upgrades' array on UpgradeFunctions to find the methods that perform upgrades between two given versions
• _performUpgrade - Calls the method on UpgradeFunctions

RecordUpgradeItem class

Methods

• getUpgrades - returns nothing. Upgrades always include one RecordUpgradeItem for the version being delivered to
• _performUpgrade - deletes temporary files (caches, proxies, &c.) and rebuilds permission lookups for those documents and folders that don't have them, and also updates the knowledgeTreeVersion system setting to the version being updated to.

UpgradeFunctions.inc.php

UpgradeFunctions class

This class contains a number of class functions that perform upgrades between versions. Attributes on this class describe what version the upgrades belong to, as well as their description and optionally the phase.

• upgrades - associative array keyed on version containing an array of the strings naming the class functions to be called for this version
• descriptions - associative array keyed on class function name that provides a description of what the function does
• phase - associative arrayed keyed on class function name that declares what phase a particular upgrade function belongs to (defaults to 0 if not given)