Meta updates

When updates are being installed for apps or plugins, it is a frequently encountered problem to modify the database structure, or to remove unnecessary source or configuration files. These actions, which are not directly connected with updating a product's source code, are called meta updates.

For automatic execution of meta updates, the new version of a product must contain correctly written PHP files with the required algorithms (e.g., for execution of SQL queries, deletion of files, etc.).

How to create meta update files

1. The file name, except for the .php extension, must consist of a valid UNIX timestamp corresponding to a later time than the time when the current, not yet updated, version was installed. Here is an example of the correct file name: 1383820487.php.
2. Source files of meta updates must be located in lib/updates/ directory or in any subdirectory inside it. For example, you may want to store meta update files of several product generations in different subdirectories: lib/updates/1/, lib/updates/2/, lib/updates/3/, etc.
3. You may use any PHP classes of the Webasyst framework and the current app in your meta update files.

4. Meta update files should be written so that they can be executed several times without negative effect. Potentially impossible operations should be included in try...catch blocks to avoid interruption of meta update execution.

   Example:

   <?php
   
   $model = new waModel();
   
   //trying to retrieve data from a potentially missing table field
   try {
       $model->query('SELECT sort FROM myapp_item WHERE 0');
   
   //in case of a failure, if the field is really missing, add it to table
   } catch (waDbException $e) {
       $sql = 'ALTER TABLE myapp_item ADD sort INT(11) NOT NULL DEFAULT 0';
       $model->exec($sql);
   }

How meta updates are installed

At the first attempt to run the product, just updated using the Installer, the database value named update_time for that product is retrieved from table wa_app_settings. After that, all available meta update files are being executed in the chronological order, whose names contain timestamps greater than the one retrieved from the database. Should the execution of some meta update file fail, the remaining files will not be executed either. Upon successful completion of the meta update, the current timestamp is saved instead of the old update_time value in the database.