Developers/Implement extensions/Setup tasks

Setup tasks are scripts, used to carry changes on the database structure between different verions. After any update using the phing setup function these scripts are run to ensure the use of the latest database structures as if the current version would have been installed from the scratch.

Process flow
While running the phing setup the MW_Setup_Manager searches the folder given in the manifest core setups and "ext/NAME_OF_EXTENSIONS/lib/custom/setup/mshop/" for extension setups. The found files are tested for corresponding classes (see "Naming conventions"). The found tasks are placed into an array. Also the dependencies of each task is stored (see "Dependencies"). Successfully run setup tasks are stored in a global array and skipped on a second call.

Each tasks has to check by itself, if it has to be run or if the changes it's going to perform are necessary. So the setup is completed faster if there are no changes and you minify the altering statements fired towards the database.

All changes made in the setup tasks should also be alligned in the database schema. So new installations don't have to run all of the tasks.

One setup task should only contain related statements. e.g. changing the same index on different tables. Or several changes on one table.

Altering setup tasks
An existing setup task which is already located in the repository should never be changed. Instead a new task has to be written, which corrects the changes made by the existing one.

Naming conventions
The name of a setup task should shortly describe it's purpose. Starting with an uppercase, no separations between words and every word starting uppercase. e.g. "ChangeAllPrimaryKeys". The filename has to be the Name of the task ("ChangeAllPrimaryKeys.php") and the class name needs the prefix "MW_Setup_Task_" ("class MW_Setup_task_ChangeAllPrimaryKeys").

Database types
A setup task has to provide a run function for each database type it's going to support. At the current state, there is only support for MySQL by default. The naming conventions for these functions is "_" plus the database type in lowercase. For MySQL it's "public function _mysql". These functions should execute the database specific altering statements.

Dependencies
Each setup task has to implement the functions "getPreDependencies" and "getPostDependencies", each returning an array containing the names of other setup tasks depending on the current task or which the current task depends on. Tasks across several domains should be avoided. Here lies a huge risk for circular dependencies which are causing exceptions.

Pre dependencies
Contains tasks which have to be completed successfully, before the current task is started. Here you should put every setup task, already altering the tables you are going to change. You don't have to set a dependency on tasks a second time which is defined as pre dependency of a task you're already depending on.

Common pre dependencies:

Example (PriceRenameColumnPriceToValue):

Post dependencies
Here you can define, which already existing tasks should be started after the current task. If you've written several tasks at once, you shouldn't connect them using post dependencies. Instead rely on pre dependencies to keep the flow of the tasks more clearly arranged.

Common post dependencies: TablesCreateMShop

Example: