Application Update Scripts

What is this article for

This article shows you how to make DB structure or data manipulations for new CB releases and the same for customization projects.

Concept

For any code you commit that needs DB changes, you make an upgrade script (in a certain directory). CB checks for new upgrade scripts and processes them on app init. So when you commit or deploy code on the involved remote installations, your scripts will handle all DB changes.

There is a directory containing PHP files that handle any necessary upgrade steps.
That directory is in appDir/helpers/updates for core code and customizationDir/updates for customization code
Each of these files use version numbers as file names (not necessarily CB release version numbers). E.g. 3.2.0.22.php.
The application keeps track of the highest version number that got processed successfully.
During app initialisation, the app lists the files and loads new files in the right order
On Exceptions, the upgrade procedure halts, a notice appears on the CB dashboard and upgrade scripts won't run again until the situation is rectified

Behaviour on upgrade failures

Each script throws Exceptions in case anything does not go as intended
The Exception messages are logged in the app's log directory in the log file configbox_upgrade_errors and a message will appear in the CB dashboard.
The failure will be remembered in the table #__configbox_system_vars: key failed_update_detected, value 1.
On subsequent page loads with CB code, the failed script (and any subsequent scripts) will NOT be tried again (you fix the issue at hand and then remove the failed_update_detected flag).
In the system vars table you will see the last successfully processed upgrade file (key latest_update_version, value is the name of the file)
In the CB dashboard you will see an entry at 'Critical Issues' notifying you that there was a failure in the upgrade procedure.

Update Scripts for customizations

There is an upgrade script system analogue to the system's upgrade script.

The location for customization upgrade scripts is in customizationDir/updates.
In table #__configbox_system_vars you find the last successfully processed file in latest_customization_update_version.
On failures, the app logs errors in configbox_upgrade_errors and flags the failure in system vars key failed_update_detected (same as for core issues). Also, you will see a message in the CB dashboard
On failures, the app will not try upgrade scripts again. In case of a failure, you rectify the situation, remove the flag failed_update_detected and retry processing the upgrade scripts.

Examples

Say you mean to add a table #__configbox_external_product_appends for a customization. You check the directory customizationDir/updates and find the next version number - say it’ll be 1.0.11.

Create the 1.0.11.php

<?php
defined('CB_VALID_ENTRY') or die();

if (ConfigboxUpdateHelper::tableExists('#__configbox_external_product_appends') == false) {
  $db = KenedoPlatform::getDb();
  $query = "...sql query to create the table...use #__ as table prefix..";
  $db->setQuery($query);
  $db->query();
}

Useful methods for checking the current DB structure

$tableName always needs the #__ table prefix:

ConfigboxUpdateHelper::tableExists($tableName) : boolean

ConfigboxUpdateHelper::tableFieldExists($tableName, $columnName) : boolean

ConfigboxUpdateHelper::getKeyNames($tableName, $columnName) : string[] - Returns an array of SQL key names for the given column

ConfigboxUpdateHelper::getColumnNames($tableName) : string[] - Returns an array of column names for the given table

ConfigboxUpdateHelper::getFkConstraintName($tableName, $columnName) : string[] - Returns an array of foreign key constraints related to the given column

Best Practices

Test upgrade scripts very thoroughly before committing to VCS or deployment - be aware of how much effort goes into rectifying a messy situation with upgrades
Before committing to VCS, see if colleagues already committed an upgrade script of the same name. DO NOT MERGE, but pick the next version number and check how both scripts will interplay
Make use of the methods in ConfigboxUpdateHelpers to keep the scripts easily readable.