When do you feel yourself bored? I have such feeling every time I used to repeat similar actions again and again. When you build something big you often need to do a lot of small movements just to fit to the environment. And this theory is especially applicable to the programming. Almost all the frameworks and platforms dictate us the structure of the project and common actions which should be repeated to do this or that and Magento is not an exception here. When you create your own module you have to write something to config, implement some interfaces, build the common directories structure. Sometimes you forget what to write and you do these find-copy-paste-change-a-bit actions. Boring. Someday you start thinking about automating this routine and here is the tool which will help you: mage tool.

Let’s start from the most interesting — an example. All that installation instructions will be at the end of this post.

New module

Imagine that we have clean magento installation and want to create a new module called “Magetool” under company namespace “Mycompany”. You open the terminal window and go to the magento root directory and type:

zf create mage-module mycompany/magetool

And you will see it prompting you to answer some questions first:

Since mage tool is seeing you first time in this project (recognizes by directory path) and there is an common opinion that source file should be followed with documentation, you are suggested to introduce yourself with information which will be included to the doc blocks. This should be done only once for the project so it will not bother you often:

That’s it. Let’s look what we have now:
1. License and author information saved to future use
2. Module configuration file under app/etc/modules

It will contain the following xml:

<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * Mycompany extension for Magento
 *
 * Long description of this file (if any...)
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade
 * the Mycompany Magetool module to newer versions in the future.
 * If you wish to customize the Mycompany Magetool module for your needs
 * please refer to http://www.magentocommerce.com for more information.
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @copyright  Copyright (C) 2011
 * @license    http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
-->
<config>
    <modules>
        <Mycompany_Magetool>
            <active>true</active>
            <codePool>local</codePool>
        </Mycompany_Magetool>
    </modules>
</config>

As you may see the file has documentation block and default config structure for working module.
3. Module config.xml file under app/code/local/Mycompany/Magetool/etc

And it will have the following dummy content:

<?xml version="1.0" encoding="UTF-8"?>
<!--
/**
 * Mycompany extension for Magento
 *
 * Long description of this file (if any...)
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade
 * the Mycompany Magetool module to newer versions in the future.
 * If you wish to customize the Mycompany Magetool module for your needs
 * please refer to http://www.magentocommerce.com for more information.
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @copyright  Copyright (C) 2011
 * @license    http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */
-->
<config>
</config>

Adding

Now we have a blank module which is ready to be filled with new models,blocks and helpers. Let’s create a model. Staying in the root of your magento folder execute the following:

zf add mage-model magetool/first

Here we specified the models namespace magetool. Since it does not exist in any of local modules the tool asks about the module name where to put new model. And we type mycompany/magetool

That’s it, new model dummy is ready. Let’s see what has been crated more detailed:
1. Model class file First.php under app/code/local/Mycompany/Magetool/Model

The content of First.php is the following:

<?php
/**
 * Mycompany extension for Magento
 *
 * Long description of this file (if any...)
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade
 * the Mycompany Magetool module to newer versions in the future.
 * If you wish to customize the Mycompany Magetool module for your needs
 * please refer to http://www.magentocommerce.com for more information.
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @copyright  Copyright (C) 2011 Your Sweet Company
 * @license    http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */

/**
 * Short description of the class
 *
 * Long description of the class (if any...)
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @subpackage Model
 * @author     Daniel
 */
class Mycompany_Magetool_Model_First extends Mage_Core_Model_Abstract
{
}

You see that there is a blank class construction written by Magento standard, doc block with author, license and other information which should be included to the class file. So everything you need to do next is write descriptions and start coding.

2. Models namespace in the module config file. Mage tool added the following lines to the etc/config.xml:

    <global>
        <models>
            <magetool>
                <class>Mycompany_Magetool_Model</class>
            </magetool>
        </models>
    </global>

Now magetool models namespace will be recognized by Magento and you may start using your new model by writing Mage::getModel(‘magetool/first’);

One more thing should be mentioned here. Since now we have magetool namespace registered, next time you will execute mage tool “add mage-model “ command it will not ask you for the target module — it will be recognized and found automatically:

What’s the profit here? Speed is the main benefit. You type 1 command in 10 seconds and get file and configuration instructions created. You don’t have to build long directories tree, write xml and copy-paste.

Along with models you could also create blocks and helpers this way:

zf add mage-block magetool/block_name

and

zf add mage-helper magetool/data

Note, that “add” commands should be executed only if your module already exists(created by “zf create mage-module” command or manually).

Rewriting

Mage tool provides you easy way to rewrite Magento models, resource models, blocks and heleprs.

Let’s imagine that we want to rewrite core catalog product model in our module. Open the terminal, go to the Magento root directory and execute:

zf rewrite mage-model mycompany/magetool catalog/product catalog_product

Command “zf rewrite mage-model” requires 3 arguments after it:
1. You module name in format company/module. We write mycompany/magetool
2. Magento model path. We write catalog/product
3. Path to the rewritten model under your module. We write catalog_product

Here is what the rewrite command does:
1. Rewritten model class Product.php under app/code/local/Mycompany/Magetool/Model/Catalog

New class will have the following content:

<?php
/**
 * Mycompany extension for Magento
 *
 * Long description of this file (if any...)
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade
 * the Mycompany Magetool module to newer versions in the future.
 * If you wish to customize the Mycompany Magetool module for your needs
 * please refer to http://www.magentocommerce.com for more information.
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @copyright  Copyright (C) 2011 Your Sweet Company
 * @license    http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */

/**
 * Short description of the class
 *
 * Long description of the class (if any...)
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @subpackage Model
 * @author     Daniel
 */
class Mycompany_Magetool_Model_Catalog_Product extends Mage_Catalog_Model_Product
{
}

Note that it specified “extends Mage_Catalog_Model_Product” automatically.

2. Rewrite instructions in module config.xml class under global section.

<models>
       <catalog>
            <rewrite>
                <product>Mycompany_Magetool_Model_Catalog_Product</product>
            </rewrite>
      </catalog>
<models>

Again, you enter 1 command and have all routine stuff prepared.

Blocks and helpers have the same syntax and behavior:

zf rewrite mage-block mycompany/magetool catalog/product_view catalog_product_view

and

zf rewrite mage-helper mycompany/magetool catalog/data catalog_data

Rewriting resource models is a special case. For example you want to change the behavior of products collection model. You should simply execute a command like the following:

zf rewrite mage-rmodel mycompany/magetool catalog/product_collection catalog_product_collection

It will create rewritten class file with the following statement:

class Mycompany_Magetool_Model_Catalog_Product_Collection extends Mage_Catalog_Model_Resource_Eav_Mysql4_Product_Collection

And configuration instruction:

   <global>
        <models>
            <catalog_resource_eav_mysql4>
                <rewrite>
                    <product_collection>Mycompany_Magetool_Model_Catalog_Product_Collection</product_collection>
                </rewrite>
            </catalog_resource_eav_mysql4>
        </models>
    </global>

Note, that you did not specify magento catalog resource model namespace catalog_resource_eav_mysql4 during the command execution. You just entered catalog/product_collection and the tool found the namespace inside of Magento auctomatically. Now you don’t have to find and copy-paste if from core catalog manually each time you rewrite something. It will save you much time!

Installing / upgrading

The last feature in current mage tool release is installing and upgrading your modules.
Imagine that your new module needs to communicate with a database table which should be created before, so you need an installer file where you will put the table creation code. With mage tool you simply write:

zf install mage-module mycompany/magetool 1.0.0

There are 2 arguments for the command:
1. Module path in format of company/module. We write mycompany/magetool
2. Initial version. We write 1.0.0

And it will create:
1. Installer file under module sql directory:

The content of installer file is the following:

/**
 * Mycompany extension for Magento
 *
 * Long description of this file (if any...)
 *
 * NOTICE OF LICENSE
 *
 * This source file is subject to the Open Software License (OSL 3.0)
 * that is bundled with this package in the file LICENSE.txt.
 * It is also available through the world-wide-web at this URL:
 * http://opensource.org/licenses/osl-3.0.php
 *
 * DISCLAIMER
 *
 * Do not edit or add to this file if you wish to upgrade
 * the Mycompany Magetool module to newer versions in the future.
 * If you wish to customize the Mycompany Magetool module for your needs
 * please refer to http://www.magentocommerce.com for more information.
 *
 * @category   Mycompany
 * @package    Mycompany_Magetool
 * @copyright  Copyright (C) 2011 Your Sweet Company
 * @license    http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 */

$installer = $this;
$installer->startSetup();
$installer->endSetup();

2. Setup configuration in module config.xml

    <modules>
        <Mycompany_Magetool>
            <version>1.0.0</version>
        </Mycompany_Magetool>
    </modules>
    <global>
        <resources>
            <mycompany_magetool_setup>
                <setup>
                    <module>Mycompany_Magetool</module>
                    <connection>core_setup</connection>
                </setup>
            </mycompany_magetool_setup>
        </resources>
    </global>

So you only need to code the table creation now, no routine work.

Upgrading modules is available in 2 modes:
1. Upgrade to exact version.

zf upgrade mage-module mycompany/magetool to 1.0.1

2. Upgrade to incremented version

zf upgrade mage-module mycompany/magetool inc *.*.1

*.*.1 here means that 2 first version segments should be the same as now, but third segment shold be incremented in 1. For example: you current module version is 3.0.5 and you want to increment the version to be 3.1.6. You execute the upgrade command with argument *.1.1.
This may be helpful when you don’t remember the current version and don’t want to spend time opening the config, but just want to write upgrade script for version + 1.

The result of above command will be:
1. Upgrade script file under module sql directory

2. Upgraded version in module config

    <modules>
        <Mycompany_Magetool>
            <version>2.0.0</version>
        </Mycompany_Magetool>
    </modules>

Mage tool installation

Here are installation instructions for Linux users. Mage tool is built on zend tool framework and if you have another OS the process should be the same except difference in zend tool installation: http://framework.zend.com/manual/en/zend.tool.framework.html

• Download Zend Framework (minimal package)
• Extract Zend Framework archive somewhere like /home/username/lib/ZendFramework
• Create symbolic link to Zend Framework: ln -s /home/username/lib/ZendFramework/bin/zf.sh /usr/local/bin/zf
• Execute zf –help and ensure it works
• Download latest mage tool release from github (“Downloads” button): https://github.com/dankocherga/MTool
• Extract it to the library directory /home/username/lib/MTool
• On this step lib directory will contain ZendFramework and MTool
• Under the home directory create file ~/.zf.ini
• Paste the following 2 lines inside:php.include_path=”.:/home/username/lib/MTool:~/lib/ZendFramework/library:/usr/bin/pear” basicloader.classes.1 = “MtoolManifest”
• Execute zf info mtool to ensure it’s working
• Browse to the magento project root and then execute tool commands

The above tutorial described all current mage tool features, for more detailed manual visit the project wiki: https://github.com/dankocherga/MTool/wiki

If you have any suggestions or found a bug, please post it to the issue tracker: https://github.com/dankocherga/MTool/issues

*** enjoy coding ***