Create or update blocks and pages via Upgrade Scripts

What are the upgrade scripts good for

Upgrade scripts can be used to change the database, whether updating values or modifying the database structure. The effect of these database changes can then be seen in admin panel and potentially on the frontend depending on what they are changing. But let’s keep it simple for now, in this post I will only talk about the upgrade scripts to create or update blocks and pages in magento admin.

The first script written for a module is usually an install script. Any consecutive scripts written for a module are called an upgrade script.

Why are they helpful

Running the scripts will automatically update the database when deploying your site to staging and production servers by hitting the url. This can help you to avoid manual setup changes in admin panel when releasing sites to different servers. It also helps us to keep track of all the changes we trigger in admin panel.

Creating Module for upgrade scripts

To run upgrade script, we need to create a custom module, but we are not going to create a whole new module now as it’s beyond the scope of this article. I’m going to use meanbee core module, which you can grab from our github repo. Our package name is therefore going to be Meanbee and module name Core. Meanbee/Core module already has a setup class that is useful for creating and updating cms pages, static blocks and transactional emails.

Copy the Meanbee/Core module to your app/code/community/ directory. You can also install it with Modman or Composer.

For better understanding, let’s define the basic module components here:

• Block: Class instance of frontend templates. Frontend templates directly use class functions.
• etc: An XML file contains module related configurations.
• Helper: As the name suggests, classes that contain functions which can be accessible across all modules as a helper, regardless of module scope.
• Model: Contain business logic same as in the typical MVC pattern.
• data: Will be created by us and it will contain your upgrade scripts related to inserting any data into the database (e.g. block and page creation).
• sql: Would be created by us, if we want to write upgrade scripts for any structural changes to the database.

1) Go to Meanbee/Core/etc/config.xml

The config.xml file contains couple of entries. One tells magento about the latest install script version:

<config>
    <modules>
        <Packagename_Modulename>
            <version>0.1.0</version>
        </Packagename_Modulename>
    </modules>
    ...
</config>

and the second one <resources> tells magento where to find the install/upgrade script setup files:

<global>
    ...
    <resources>
        <meanbee_core_setup>
            <setup>
                <module>Meanbee_Core</module>
                <class>Meanbee_Core_Model_Resource_Setup</class>
            </setup>
        </meanbee_core_setup>
    </resources>
    ...
</global>

2) Go to Meanbee/Core/data and create new folder meanbee_core_data_setup where you will place all your script files. The name of your script file would be install-0.0.1.php (for the first script) or upgrade-0.0.1-0.0.2.php (version number grows as you run new upgrades).

Lets say we want to run upgrade script to create CMS block in admin. The script would look like this:

<?php
/**
 * Add CMS blocks on Product page
 */

/** @var Meanbee_Core_Model_Resource_Setup $installer */

$installer = $this;

$installer->startSetup();

$installer->createCmsBlock(
    "block-identifier",
    "block Title",
    "block content goes here e.g. Editable content block - ability to include graphics, text & links",
    Mage::app()->getStore('en_za')->getId()
);

$installer->endSetup();
?>

The function we are using is from our Setup.php file in following directory: app/code/local/Meanbee/Core/Model/Resource/Setup.php

<?php
public function createCmsBlock($identifier, $title, $content, $stores = array(0))
    {
        $current_store = Mage::app()->getStore();
        Mage::app()->setCurrentStore(Mage_Core_Model_App::ADMIN_STORE_ID);

        Mage::getModel("cms/block")
            ->setData(array(
                "identifier" => $identifier,
                "title"      => $title,
                "content"    => $content,
                "is_active"  => 1,
                "stores"     => $stores
            ))
            ->save();

        Mage::app()->setCurrentStore($current_store);
        return $this;
    }
?>

Running Upgrade Scripts

Don’t forget to update your config.xml file to the correct script version. To run your script, open your magento shop in browser. Everytime you refresh a page, magento checks if there is anything that needs to be installed and installs new scripts.

Tips

When developing your scripts, you might want to test your install/upgrade script several times until you get it right. Once the script is run and makes an entry into its core_resource database table, it will no longer run installation script with the same or lower installation version number. What you can do in such cases, is to manually delete the entry from core_resource database table and re-run the same install script multiple times.

If you have Magerun installed, you can also run your scripts by running the magerun command: n98-magerun.phar sys:setup:incremental.