Developers/Setup tasks/Basics

Advantages
The setup tasks have a lot of advantages and exceed the possibilities of other available solutions like mapping" (ORM) or similar alternatives to setup tasks:


 * The database structure is stored in the version control system
 * For every commit there can be a suitable database structure created
 * Everyone can update his existing database to a newer version
 * Updates are possible from any commit, not only from released versions
 * Data transformation is possible via PHP code if SQL is not enough
 * They can declare dependencies to other tasks
 * The tasks are prepared to support several database vendors

They are also used to write the default and unit test data to the database during the setup process.

Start the setup
It's only allowed to start the setup from the command line interface. Depending on the setup tasks executed and the amount of records in the Arcavias database, it can be a rather long lasting process. Thus, it would be possible to start a denial of service attack if anyone would be able to start the process via the web server.

The process is initiated by the setup.php in the main directory of the Arcavias core. You can call it directly or via phing to perform different tasks:


 * php setup.php for creating or updating the database structure, there are also some more options.
 * phing setup to create the unit test data (including the structure)
 * phing setupperf to create the performance test data (including the structure)

The setup process
There can be several directories which contain setup tasks. The main directory inside the Arcavias core is lib/mshoplib/setup/, which is configured in the manifest.php file. Extensions can provide setup tasks in their own directories as well, as long as they are also configured in their own manifest.php file.

Each setup task can declare dependencies to other tasks, e.g. that a list of tasks must be executed before this task can run and that e.g. one task must be executed after the task completed. There will be more information about pre- and post-dependencies later as they require some more attention. The important thing during the setup process is that all tasks from all configured setup directories are sorted according to their dependencies and are executed in that order.

There are four types of setup tasks:


 * 1) Those, which declare no dependencies to other tasks and are not listed as post-dependencies in other tasks. There are only a few ones because usually, each task has one or more dependencies.
 * 2) Next are the tasks that depend on other tasks. Maybe they want to change columns that have been changed before by other tasks. New columns that should be inserted next to columns created by other tasks are another reason. In an empty database most of these setup tasks will exit immediately because the first check is always if the necessary database table exists. Therefore, the task for creating the tables is always executed after the ones changing tables in an existing database. This reduces the time for the setup process drastically for new installations.
 * 3) The task for creating the tables and indexes is executed very late in the process. It reads the schema files in e.g. lib/mshoplib/setup/default/schema/mysql/</tt> for the Arcavias core and executes the SQL statements if necessary.
 * 4) Tasks executed afterwards either need the new tables for migrating data from old ones or they will insert records into those tables. There are tasks that insert some default records e.g. for the product types. Furthermore, some tasks are executed only for specific sites: The test sites (unittest and unitperf) contain their own tasks that insert or generate the required test records. One of the last tasks is usually the one for rebuilding the index for fast search operations.

Each task tests if the part of the database schema that it's written for is already up to date and prints what tables it checks. If nothing has to be done, it will only print "OK". Otherwise, it performs the necessary changes and tell you what has been done.

Next: Implementing setup tasks >>