When installing a new module, Magento allows installation scripts to be fired. This allows you to install database tables, insert or manipulate data, and do many other things as well. You can create directories, verify a valid license, and anything else your heart desires. The main use is database manipulations.
So how does it do this? When Magento fires up, (ie. loads), Magento calls Mage_Core_Model_App::run() . This calls a protected method called _initModules() . This does a check and then fires the meat and potatoes: Mage_Core_Model_Resource_Setup::applyAllUpdates() . Mage_Core_Model_Resource_Setup is where the magic happens. If you start at applyAllUpdates() and follow it down, you will see there are two areas where Magento looks for installation scripts. a folder called sql and a folder called data. It looks for installation files.
Magento will load both php files and sql files in these folders. If it is a sql file, it will execute all queries from within that file. Make sure you do all other necessary checks required (foreign key check flags, database prefixes, etc.) inside this file, as there is no abstraction layer available with the sql file. Most people use php files for their installation scripts.
Installation files follow this syntax:
- (same for sql files, just a different file extension: .sql)
the word “install” followed by a hyphen (-) and then the version number.
Upgrade files follow this syntax:
If an upgrade, there must be a hyphen between each version number so they know which version you are upgrading to.
Magento is a smart cookie and can determine how upgrade paths are followed. It does this via the version number you reference.
For example, if you have a module that has gone through versions 1.0, 2.0, and 3.0 with each major version having two sub-sets, (i.e. 1.1, 1.2, etc), Magento follows the installation and upgrade path for each version. In this example, Magento would go like this:
- … and so on.
Magento is also smart enough to reference the initial install file you determine based upon the version number. For example, if an early adopter installs your module at version 1.0, Magento would trigger install-1.0.php. But if you include a install-2.0.php file in your folder, and someone installs from 2.2, it would start with install-2.0.php!
So, it would look like this:
Early adopter – version 1.0:
Normal adopter – version 2.2:
This means your file structure inside your sql folder would look like this:
You can also skip versions if desired. The only catch is that you cannot have version numbers in between, or Magento will try to install those files as well.