How To Create Setup File For A Custom Magento Module
In this post we’ll take an in-depth look at creating a setup file for a custom module. We looked at this briefly in my previous post on creating custom modules on Magento.
If you create your own custom modules for Magento, chances are that at some point you will need your module(s) to be able to persist data to the database. This is where the installation scripts come into play.
In order to create setup file, we first need to specify the setup resource in our config.xml file. To do so, go to app/code/local/Folio3/Feedback/etc and open the file titled config.xml and under the global tag add the as shown below.
In this tutorial, the custom module is named Feedback and it is located in the Folio3 folder, so the setup tag will be folio3_feedback_setup. Since we have only one database in our project we don’t need to include the connection tag. Now that we are done with the config.xml file changes, let us move on to setup file.
The setup file resides in the sql folder of any module (as shown below).
Open the sql folder and create a new folder in it named folio3_feedback_setup. If you’re creating a setup file for the first time, then the naming convention of the setup file will be install-.php. If you are not sure of your module’s version number, you can always check it in your config.xml file (depicted below).
In this case the module version number is 0.0.1, so the name of our setup file will be install-0.0.1.php. Open this file and write the following code in it.
$installer = $this;
$installer->run("CREATE TABLE IF NOT EXISTS `" . $this->getTable("folio3_feedback") . "` (
`id` int unsigned NOT NULL auto_increment,
`customer_name` varchar(200) NOT NULL,
`customer_email` varchar(200) NOT NULL,
`customer_feedback` text NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=INNODB charset=utf8 COLLATE=utf8_unicode_ci COMMENT='this table is for customer feedback'");
The above given script is pretty straight forward. First we’re calling $installer = $this. Since each installer script is run from the context of a Setup Resource class (the class we created above), any reference to $this from within the script will be a reference to an object instantiated from this class. You’ll also notice that the queries in the script above are bookended by the following two method calls.
The startSetup() method will execute the sql setup for MySQL connections and the endSetup() method will end it.
You will also notice that $installer->getTable(..) allows you to pass in a Magento Model URL and get its table name. We have also called the $installer->run(…) method, which accepts a string containing the SQL needed to setup your database table(s). You can specify any number of queries, separated by a semi-colon.
Basically what we have did in this script is create a new table called folio3_feedback with following fields:
- ID (integer)
- Customer Name (varchar)
- Customer Email (varchar)
- Customer Feedback (text)
The ID field is also the primary key of our table.
Now suppose you need to add another field to this table in the future. In that case you’ll need to create yet another script file and the naming convention for this file will be upgrade-<current module version>-<future module version>.php. In order to do that we have to upgrade the version number of our module in the custom module’s config.xml file. In this case we will upgrade the version number from 0.0.1 to 0.0.2.
So the name of updated script file will be upgrade-0.0.1-0.0.2.php. After doing that you just have to clear the magento cache and the script will be automatically executed.
And that’s it. Hopefully this tutorial will give you a good idea about how to create a setup file for your custom modules.
Latest posts by Kashif Saleem (see all)
- How To Create Setup File For A Custom Magento Module - March 2, 2016
- HOW TO CREATE A CUSTOM MAGENTO MODULE - July 13, 2015