MagentoSetup Resources

Adding the Setup Resource

 

<resources>

    <!-- ... -->

    <weblog_setup>

        <setup>

            <module>Bysoft_Weblog</module>

            <class>Bysoft_Weblog_Model_Resource_Mysql4_Setup</class>

        </setup>

        <connection>

            <use>core_setup</use>

        </connection>

    </weblog_setup>

    <!-- ... -->

</resources>

 

The <weblog_setup> tag will beused to uniquely identify this Setup Resource. It’s encouraged, but notnecessary, that you use the modelname_setup namingconvention.

The <module>Bysoft_Weblog</module> tag block should contain the Packagename_Modulename of your module.

Finally, <class>Bysoft_Weblog_Model_Resource_Mysql4_Setup</class> should contain the name of the classwe’ll be creating for our Setup Resource.

Creating our Installer Script

 

First, take a look at your config.xml file

<modules>

    <Bysoft_Weblog>

        <version>0.1.0</version>

    </Bysoft_Weblog>

</modules>

This section is required in all config.xml files, and identifies the module as well as the its version number. Your installer script’s name will be based on this version number.

Create file: app/code/local/Bysoft/Weblog/sql/weblog_setup/mysql4-install-0.1.0.php

The weblog_setup portion of the path should match the tag you created in your config.xml file (<weblog_setup />).

The 0.1.0 portion of the filename should match the starting version of your module.

 

Resource Versions

 

Magento’sSetup Resources allow you to simply drop your install scripts (and upgradescripts, which we’ll get to in a bit) onto the server, and have the systemautomatically run them.

The table core_resource contains a list of all the installed modules, along with theinstalled version number.This is how Magento knows not to re-run your script onthe second. If you want to re-run your installer script (useful when you’redeveloping), just delete the row for your module from this table.

We’ll also want to drop the table we manually created in the previous article. 

DROP TABLE blog_posts;

 

Then, add the following code to your setup script(Here is mysql4-install-0.1.0.php).

$installer = $this;

$installer->startSetup();

$installer->run("

    CREATE TABLE `{$installer->getTable('weblog/blogpost')}` (

      `blogpost_id` int(11) NOT NULL auto_increment,

      `title` text,

      `post` text,

      `date` datetime default NULL,

      `timestamp` timestamp NOT NULL default CURRENT_TIMESTAMP,

      PRIMARY KEY  (`blogpost_id`)

    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

    INSERT INTO `{$installer->getTable('weblog/blogpost')}` VALUES (1,'My New Title','This is a blog post','2009-07-01 00:00:00','2009-07-02 23:12:30');        

");

$installer->endSetup();

Clear your Magento cache and reload any page in the system. You should have a new blog_posts table with a single row.

Anatomy of a Setup Script

So, let’s go over the script line-by-line.

First, there’s this(or is that $this?)

$installer = $this;

Any reference to $this from within the script will be a reference to an object instantiated from it’s Setup Resource class(Here  is Bysoft_Weblog_Model_Resource_Mysql4_Setup class)

Next, you’ll see our queries are bookended by the following two method calls.

$installer->startSetup();

//...

$installer->endSetup();

If you take a look at the Mage_Core_Model_Resource_Setup class in app/code/core/Mage/Core/Model/Resource/Setup.php (which your setup class inherits from) you can see that these methods do some basic SQL setup

Finally, there’s the call to the run method

$installer->run(...);

which accepts a string containing the SQL needed to setup your database table(s). You may specify any number of queries, separated by a semi-colon.

$installer->getTable('weblog/blogpost')

The getTable method allows you to pass in a Magento Model URI and get its table name. Using this method ensure that your script will continue to run, even if someone changes the name of their table in the config file.

Module Upgrades

Magento’s Setup Resources support a simple versioning scheme that will let you automatically run scripts to upgrade your modules.

Once Magento runs an installer script for a module, it will never run another installer for that module again.Instead, you’ll need to create an upgrade script. Upgrade scripts are very similar to installer scripts, with a few key differences.

File: app/code/local/Bysoft/Weblog/sql/weblog_setup/mysql4-upgrade-0.1.0-0.2.0.php

Upgrade scripts are placed in the same folder as your installer script, but named slightly differently.

First, and most obviously, the file name contains the word upgrade. 

Secondly, you’ll notice there are two version numbers, separated by a “-“. The first (0.1.0) is the module version that we’re upgrading from. The second (0.2.0) is the module version we’re upgrading to.