Getting Started with Magento Extension Development: This practical guide to building Magento modules from scratch takes you step-by-step through the whole process, from first principles to practical development. At the end of it you'll have acquired expertise based on thorough understanding.

Once you download the full release and set up your work environment, you should see a root Magento folder structure with the following files and folders in it:

Throughout this book we will be referencing our URL examples as if they are executing on the magento.loc domain. You are free to set your local Apache virtual host and host file to any domain you prefer, as long as you keep this in mind. If you're hearing about virtual host terminology for the first time, please refer to the Apache Virtual Host documentation at http://httpd.apache.org/docs/2.4/vhosts/.

Here is a quick summary of each of those files and folders:

Now that we have covered the basic root folder structure, it's time to dig deeper into the most used folder of all, the app folder, as shown in the following diagram:

app/
├── Mage.php
├── code
│   ├── community
│   │   └── Phoenix
│   │       └── Moneybookers
│   └── core
│       ├── Mage
│       └── Zend
├── design
│   ├── adminhtml
│   ├── frontend
│   │   ├── base
│   │   │   └── default
│   │   │       ├── etc
│   │   │       ├── layout
│   │   │       └── template
│   │   └── default
│   │       ├── blank
│   │       ├── default
│   │       ├── iphone
│   │       └── modern
│   └── install
├── etc
│   ├── config.xml
│   ├── local.xml.additional
│   ├── local.xml.template
│   └── modules
└── local
    └── en_US

The folder code is a placeholder for what is called a codePool in Magento. Usually, there are three code pools in Magento, that is, three subfolders: community, core, and local.

The folder local is sometimes missing from the downloaded installation archive, as it is empty by default.

Let's take a deeper look at the community codePool for the default Magento installation as shown in the following diagram:

community/
└── Phoenix
    └── Moneybookers
        ├── Block
        │   ├── Form.php
        │   ├── ...
        │   └── Redirect.php
        ├── Helper
        │   └── Data.php
        ├── Model
        │   ├── Abstract.php
        │   ├── ...
        │   └── Wlt.php
        ├── controllers
        │   ├── MoneybookersController.php
        │   └── ProcessingController.php
        ├── etc
        │   ├── config.xml
        │   └── system.xml
        └── sql
            └── moneybookers_setup
                ├── install-1.6.0.0.php
                └── mysql4-upgrade-1.2-1.2.0.1.php

Here, the Phoenix folder is what is called the vendor namespace, and it usually matches your company identifier or something else unique to you. Within the Phoenix folder there is a Moneybookers subfolder that stands for your actual extension name.

To summarize, the formula for your extension code location should be something like app/code/community/YourNamespace/YourModuleName/ or app/code/local/YourNamespace/YourModuleName/.

There is a simple rule as to whether to choose community or local codePool:

For example, let's imagine that our company name is Foggyline and the extension we are building is called Happy Hour . As we wish to share our extension with the community, we can put it into a folder such as app/code/community/Foggyline/HappyHour/.

All the Magento core code is also divided into extensions, and is located under the app/code/core/Mage folder. You should never place any of your code or edit any of the existing code under the app/code/core folder.

Let us get back to our example from the previous listing, the Moneybookers extension. We can see that it has several subfolders within it:

With that said, we will temporarily conclude our trip to the app/code folder structure and move on to the app/etc/modules folder.

This folder is basically a starting point for every Magento extension. The following listing shows the default content of the app/etc/modules folder for the default Magento installation, which is a collection of XML files:

For example, if we were to create our Foggyline/Happy Hour extension, we would need to create a file app/etc/modules/Foggyline_HappyHour.xml as we will show later on.

Next, we move onto the app/local folder. This is where the translation files reside. If you were building an extension that would support multiple languages, for example English and German, you might want to create the following files:

The exact filename in this case does not have to be Foggyline_HappyHour.csv; this is something that is set by you within the extension configuration.

In order to successfully build extensions that visually manifest themselves to the user either on the backend or frontend, we need to get familiar with the theme system. The theme system is comprised of two distributed parts: one found under the app/design folder and the other under the root skin folder. Files found under the app/design folder are PHP template files and XML layout configuration files. Within the PHP template files you can find the mix of HTML, PHP, and some JavaScript.

The structure of the app/design folder is shown in the following diagram:

app/
├── design
│   ├── adminhtml
│   ├── frontend
│   │   ├── base
│   │   │   └── default
│   │   │       ├── etc
│   │   │       ├── layout
│   │   │       └── template
│   │   └── default
│   │       ├── blank
│   │       ├── default
│   │       ├── iphone
│   │       └── modern
│   └── install

There are three main subfolders here as follows:

Once you step into one of them you should see a list of so called packages.

For example, stepping into the frontend shows two packages available, base and default. Drilling down into individual packages, come themes. For example, the package default has four themes in it: blank, default, iphone, and modern. By default, once you install the Magento package the initial active theme is default within the default package.

You will often hear about the frontend developer using a shorthand when talking about theme; for example, if they say default/hello, it would mean the default package with the theme named hello.

There is one important thing to know about Magento themes; they have a fallback mechanism; for example, if someone in the administration interface sets the configuration to use a theme called hello from the default package; and if the theme is missing, for example, the app/design/frontend/default/hello/template/catalog/product/view.phtml file in its structure, Magento will use app/design/frontend/default/default/template/catalog/product/view.phtml from the default theme; and if that file is missing as well, Magento will fall back to the base package for the app/design/frontend/base/default/template/catalog/product/view.phtml file.

We won't get into the details of Magento design packages and themes. There is plenty to be said about this topic that could fit into a new book. For the purpose of this book, there are a few things that you need to know as a Magento extension developer in terms of writing unobtrusive extensions.

Firstly, all your layout and view files should go under the /app/design/frontend/defaultdefault/default directory.

Secondly, you should never overwrite the existing .xml layout or template .phtml file from within the /app/design/frontend/default/default directory, rather create your own. For example, imagine you are doing some product image switcher extension, and you conclude that you need to do some modifications to the app/design/frontend/default/default/template/catalog/product/view/media.phtml file. A more valid approach would be to create a proper XML layout update file with handles rewriting the media.phtml usage to, let's say, media_product_image_switcher.phtml.

This might not make much sense for you now; but once you get your head around layout updates, the idea will be pretty clear. We will now temporarily conclude our trip to the app/design folder structure and move on to the root skin folder. The structure of the skin folder is similar to that of app/design, as shown in the following diagram:

skin/
├── adminhtml
├── frontend
│   ├── base
│   │   └── default
│   │       ├── css
│   │       ├── favicon.ico
│   │       ├── images
│   │       ├── js
│   │       └── lib
│   │           └── prototype
│   └── default
│       ├── blank
│       ├── blue
│       ├── default
│       │   ├── css
│       │   ├── favicon.ico
│       │   └── images
│       ├── french
│       ├── german
│       ├── iphone
│       └── modern
└── install

There is not much to say about the skin folder. It's a placeholder for all your theme-specific CSS, JavaScript, and image files. If you are developing community-distributed extensions, it makes sense to reduce the usage of CSS to absolute minimum, if any, in your extension. The reason is that you cannot know which theme the user will use and how your extension visual components design will impact its theme.

The same thing cannot be said for JavaScript, as you will most likely notice yourself if you keep developing a lot of community extensions. Adding your custom JavaScript code to a skin/frontend/default/default/js folder is a nice, clean, and unobtrusive way of doing it. As the skin folder has the same fallback functionality as the app/design folder, you do not need to know upfront the theme that the user will use.

Later on, as you sharpen your Magento developer skills you might ask yourself, "Why not use the root js folder to add your JavaScript code?" Technically, you could, and it would be perfectly valid; no tricks or hacks in that approach. However, the root js folder should be looked upon as a third-party JavaScript library container, while the skin/frontend/default/default/js folder should be looked upon as your custom JavaScript extension-related code container. For example, it makes no sense to place your product image switcher extension JavaScript into the root js folder if it's a JavaScript code that works only with your extension and is not intended for general re-use.

With this we can conclude the relevant Magento folder structure that you as a Magento extension developer should be familiar with. In general, these five locations should be all to build fully functional, clean, and unobtrusive extensions:

Depending on the complexity and the functionality your extension tries to fulfill, you might end up using just a few or all of these directory locations within a single extension.

With everything said, by now we should have a solid understanding of the Magento directory structure and be ready to grasp further concepts of the Magento internal structure.

What better way to explain things than an example; so let's start off by creating the simplest extension, which we will then extend bit by bit as we explain the Magento way of doing the object-oriented Model-View-Controller (MVC) architecture. If you are hearing of MVC for the first time, please take some time to familiarize yourself with the concept. You can find good starting material about it at http://en.wikipedia.org/wiki/Model–view–controller.

Previously, we gave examples on the extension name Foggyline_HappyHour, so let's start with that.

In Magento, everything starts with a configuration file; after all, Magento is what we call the configuration-based MVC system. In a configuration-based system, in addition to adding the new files and classes, you often need to explicitly tell the system about them.

The first file we will create is app/etc/modules/Foggyline_HappyHour.xml with the following content:

<?xml version="1.0"?>
<config>
   <modules>
      <Foggyline_HappyHour>
         <active>true</active>
            <codePool>community</codePool>
      </Foggyline_HappyHour>
   </modules>
</config>

With this file in place, Magento already becomes aware of your extension. You can confirm that by going under the Magento administration under System | Configuration | Advanced | Advanced | Disable Modules Output. Once you're there, you should see your Foggyline_HappyHour extension on the list. It is important to know that setting the Disable Modules Output value to Disabled and saving the configuration has absolutely no impact on your extension being truly enabled or disabled.

Disabling the extension output is not the same as disabling the extension itself. Disabling the output of the extension via this configuration option has an effect only on your extension block classes that represent the visually output part of your extension. To truly disable the extension, one must edit the app/etc/modules/Foggyline_HappyHour.xml file and change <active>true</active> to <active>false</active>.

Now that Magento sees our extension, we move on to the next step: creating the app/code/community/Foggyline/HappyHour/etc/config.xml file. This config.xml file is what is usually referred to as the extension configuration file by developers. The following code is the basic definition of our app/code/community/Foggyline/HappyHour/etc/config.xml file:

<?xml version="1.0"?>
<config>
   <modules>
      <Foggyline_HappyHour>
         <version>1.0.0.0</version>
      </Foggyline_HappyHour>
   </modules>
</config>

By itself, the content of the app/code/community/Foggyline/HappyHour/etc/config.xml file won't have any additional effect on Magento, so let's move on to extending our extension. First, we will create a controller in order to output Hello World to the browser. To do this, we need to add the routers definition in frontend to our config.xml file.

<?xml version="1.0"?>"?>
<config>
<!-- … other elements ... -->
   <frontend>
      <routers>
         <foggyline_happyhour>
            <use>standard</use>
               <args>
                  <module>Foggyline_HappyHour</module>
                  <frontName>happyhour</frontName>
               </args>
         </foggyline_happyhour>
      </routers>
   </frontend>
<!-- … other elements ... -->
</config>

The frontend tag refers to a Magento area. Magento has three distinctive areas: frontend, admin, and install. The frontend area is what your customers see, the public facing shopping cart. The admin area is what your Magento admin users see, the administrative interface. The install area is what you see the very first time you install Magento, the installation process.

The routers tag encloses the configuration information about routers.

The frontName tag is sort of an alias for the desired route we want Magento to react to.

When a router parses a URL, it gets separated as follows: http://example.com/frontName/actionControllerName/actionMethod/. By defining a value of happyhour in the <frontName> tag, we're telling Magento that we want the system to respond to URLs in the form of http://example.com/happyhour/*.

It's important to understand that frontName and the Front Controller object are not the same thing.

The foggyline_happyhour tag should be the lowercase version of your extension name. Our extension name is Foggyline_HappyHour; this tag is foggyline_happyhour.

The extension tag should be the full name of your extension, including its namespace/extensionname name. This will be used by the system to locate your controller files.

Now we need to create a controller file. The module controller files are stored under the controllers subfolder. So let's create an app/code/community/Foggyline/HappyHour/controllers/HelloController.php class file with the following content:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{
   public function helloWorldAction()
   {
      echo 'Hello World #1.';
   }
}

Once you are done, you can try opening the following URL in the browser: http://magento.loc/index.php/happyhour/hello/helloWorld. You should be able to see the Hello World #1. message. The URL path is constructed from your config.xml router frontName, the controller name itself, and the controller action name. There are two main types of controllers in Magento:

URLs for admin controller actions can only be accessed if you are logged in to the Magento administration interface.

Looking within the helloWorldAction() method, you can see a call towards the createBlock() method with the string 'core/text' as a parameter. Where does 'core/text' come from and what does it mean? In order to understand that, we will further extend our config.xml file by adding a blocks element to it as follows:

<?xml version="1.0"?>
<config>
<!-- … other elements ... -->
   <global>
      <blocks>
         <foggyline_happyhour>
            <class>Foggyline_HappyHour_Block</class>
         </foggyline_happyhour>
      </blocks>
   </global>
<!-- … other elements ... -->
</config>

The element foggyline_happyhour is known as the class group. The element foggyline_happyhour is a class group name and its inner class element is basically a shortcut for your extensions Block type PHP classes. For example, the following is a modified code for our helloWorldAction() method shown previously:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{
   public function helloWorldAction()
   {
      $this->loadLayout();
      
      $block = $this->getLayout()->createBlock('foggyline_happyhour/hello');
      $block->setText('Hello World #2.');
      
      $this->getLayout()->getBlock('content')->insert($block);
      
      $this->renderLayout();
   }
}

You can see that we are no longer calling the createBlock() method with 'core/text' but with the 'foggyline_happyhour/hello' parameter. This is like telling Magento to load the hello class (the Hello.php file) that can be found under the classpath mapped by the foggyline_happyhour class group. As the foggyline_happyhour class group has its class value set to Foggyline_HappyHour_Block, Magento expects to find the app/code/community/Foggyline/HappyHour/Block/Hello.php file.

How and why exactly does Magento expect the Hello.php file to be at a certain location? The answer to this lies in a robust autoloading functionality of the Magento system based on a configuration and file naming convention. You can split all Magento classes into four parts that we'll call the vendor namespace, extension name, class group, and filename itself.

The vendor namespace helps us prevent name collisions between extensions, letting you know which extension is the owner of the class. For example, all core Magento extensions use the mage namespace.

The module name plays a crucial part in the autoloading system. All the proper customization of Magento is done through individual extensions.

The class group is a sort of alias defined within the extension's configuration file, an alias towards a class folder within the extension directory. There are several main types of class groups, such as the one for Model, Block, Helper.

Finally, the name of the file itself. Each class should have a unique name within a class group that describes its intended use or function.

Magento's autoloading functionality uses these parts to determine where to find the source for a given class as shown in the following example: VendorNamespace/ModuleName/ClassGroup/FileName.php.

Go ahead and create the file Hello.php with the following content:

<?php

class Foggyline_HappyHour_Block_Hello extends Mage_Core_Block_Text
{
 
}

Now that you have modified helloWorldAction() and created the Hello.php class file, go ahead and open the http://magento.loc/index.php/happyhour/hello/helloWorld URL in the browser. The result should be the same as in the previous case; you should be able to see the fully loaded Magento page with the Hello World #2. message shown under the content area.

Our Hello block class extends Mage_Core_Block_Text. However, chances are that most of the time you will be extending the Mage_Core_Block_Template class, where your Hello block class might look like something as follows:

<?php

class Foggyline_HappyHour_Block_Hello extends Mage_Core_Block_Template
{
   public function __construct()
   {
      parent::__construct();
      $this->setTemplate('foggyline_happyhour/hello.phtml');
   }
}

The difference between extending Mage_Core_Block_Text or Mage_Core_Block_Template is that the latter requires you to define a view *.phtml file under the theme folder, and thus, is more designer friendly. In order for it to successfully work, you need to create the app/design/frontend/default/default/template/foggyline_happyhour/hello.phtml or app/design/frontend/base/default/template/foggyline_happyhour/hello.phtml file. You might find the latter to be a safer location for your view files, as it is not dependent on your customer theme and package settings. Thus, the Magento theme fallback mechanism will always pick it up. Now if you put your Hello World #3. string within the hello.phtml file and then re-open the http://magento.loc/index.php/happyhour/hello/helloWorld URI in your browser, you should again see the fully loaded Magento page with the Hello World #3. message shown under the content area. Our goal here is to give you the basics of functional extension, so we will now leave the controllers and blocks behind and move to the model.

A model represents the data for the better part, and to a certain extent a business logic of your application. Models in Magento take the Object Relational Mapping (ORM) approach, thus having the developer to strictly deal with objects while their data is then automatically persisted to the database. If you are hearing about ORM for the first time, please take some time to familiarize yourself with the concept; you can find good starting material about it at http://en.wikipedia.org/wiki/Object-relational_mapping. Theoretically, you could write and execute raw SQL queries in Magento. However, doing so is not advised, especially if you plan on distributing your extensions.

There are two types of models in Magento:

Now let us create the four files required for our extensions model entity to work fully.

First we will create a model file app/code/community/Foggyline/HappyHour/Model/User.php with the following content:

<?php

class Foggyline_HappyHour_Model_User extends Mage_Core_Model_Abstract
{
   protected $_eventPrefix      = 'foggyline_happyhour_user';
   protected $_eventObject      = 'user';
   
   protected function _construct()
   {
      $this->_init('foggyline_happyhour/user');
   }
}

All basic data models, such as our Foggyline_HappyHour_Model_User, should extend the Mage_Core_Model_Abstract class. This abstract class forces you to implement a single method named _construct. Please note that this is not PHP's constructor __construct.

The _construct method should call the extending class' _init method with the same identifying URI you will be using in the Mage::getModel method call. Also, note the class-protected properties $_eventPrefix and $_eventObject . It is highly recommended, although not required, for you to define these properties. Values of both the properties can be freely assigned; however, you should follow your extension-naming scheme here as shown earlier.

Once we get to the Magento event/observer system later in the chapters, the meaning of these properties and how they make your code extendible by third-party developers will become more clear.

Every model has its own resource class. When a model in Magento needs to talk to the database, Magento will make the following method call to get the model resource Mage::getResourceModel('class_group/modelname');. Without resource classes, models would not be able to write to the database. Having that in mind, we create the model resource file app/code/community/Foggyline/HappyHour/Model/Resource/User.php with the following content:

<?php

class Foggyline_HappyHour_Model_Resource_User extends Mage_Core_Model_Resource_Db_Abstract
{
   protected function _construct()
   {
      $this->_init('foggyline_happyhour/user', 'user_id');
   }
}

Again, we have the same pattern: the construct method should call the extending class' init method with the same identifying URI, with a slight exception of the existing second parameter in this case, which matches the primary key column name in the database. So in this case, the string user_id matches the primary key column name in the database.

Finally, we address the model collection file. As Magento does not like juggling its model objects through plain PHP arrays, it defines a unique collection object associated with each model. Collection objects implement the PHP IteratorAggregate and Countable interfaces, which means they can be passed to the count function and used for each constructs.

We create the model collection file app/code/community/Foggyline/HappyHour/Model/Resource/User/Collection.php with the following content:

<?php

class Foggyline_HappyHour_Model_Resource_User_Collection extends Mage_Core_Model_Resource_Db_Collection_Abstract
{
   public function _construct()
   {
      $this->_init('foggyline_happyhour/user');
   }
}

Just as we did with our other classes we define the construct method, which calls the extending class' init method with the same identifying URI.

Finally, we create an installation script file app/code/community/Foggyline/HappyHour/sql/foggyline_happyhour_setup/install-1.0.0.0.php with the following content:

<?php

/* @var $installer Mage_Core_Model_Resource_Setup */
$installer = $this;
$installer->startSetup();

$table = $installer->getConnection()
   ->newTable($installer->getTable('foggyline_happyhour/user'))
   ->addColumn('user_id', Varien_Db_Ddl_Table::TYPE_INTEGER, null, array(
      'identity'  => true,
      'unsigned'  => true,
      'nullable'  => false,
      'primary'   => true,
      ), 'Id')
   ->addColumn('firstname', Varien_Db_Ddl_Table::TYPE_VARCHAR, null, array(
      'nullable'  => false,
      ), 'User first name')
   ->addColumn('lastname', Varien_Db_Ddl_Table::TYPE_VARCHAR, null, array(
      'nullable'  => false,
      ), 'User last name')
   ->setComment('Foggyline_HappyHour User Entity');
$installer->getConnection()->createTable($table);

$installer->endSetup();

There is one thing we need to pay special attention to here, the naming of the install-1.0.0.0.php file. The number 1.0.0.0 must be equal to the numbers placed under the version element value, or else Magento won't trigger your installation script.

Ever since version 1.6, Magento (in theory) supports more database backends than only MySQL. Thus, technically, the meaning of code within this install script may vary from database to database depending on the implementation.

Given that MySQL is still the default and far more dominant database backend for Magento, it is worth noting what actually goes on behind this installation script. It starts by calling $installer->startSetup(), which internally sets SQL_MODE to NO_AUTO_VALUE_ON_ZERO, and FOREIGN_KEY_CHECKS to 0. The call to $installer->startSetup(), on the other hand restores the two mentioned values to their previous states. The rest of the code that lies in between is responsible for the actual table definition and creation.

In our preceding example, we defined a table that will be named foggyline_happyhour_user, and three columns named user_id, firstname, and lastname.

These four files conclude our requirement for a fully persistent entity model. In order to check if everything is functioning, load any Magento URL in the browser and then take a look at the database. If the extension is installed correctly, there should be two changes to the database:

Note, if you experience issues with your installation script during their execution, such as breaking up due to invalid instructions, be sure to remove the core_resource table entry that your extension might have created. After that, simply open the browser and reload any web page from your shop; this will trigger the installation process again.

Now that we have successfully created single entity (User) model file, we need to make sure it's working. We can do so by going back to our Foggyline_HappyHour_HelloController class and adding the following action to it:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{
  /* … other code … */  
   public function testUserSaveAction()
   {
      $user = Mage::getModel('foggyline_happyhour/user');
      
      $user->setFirstname('John');
       /* or: $user->setData('firstname', 'John'); */
      
      $user->setLastname('Doe');
      /* or: $user->setDatata('lastname', 'Doe'); */
      
      try {
         $user->save();
         echo 'Successfully saved user.';
      } catch (Exception $e) {
         echo $e->getMessage();
         Mage::logException($e);
/* oror: Mage::log($e->getTraceAsString(), null, 'exception.log', true); */
      }
   }
  /* … other code … */  
}

Models in Magento get called (instantiated) all across the code. Instantiating the model class is done by the statement $model = Mage::getModel('classGroup/modelClassName); which can be seen in the preceding code.

What confuses most of the Magento newcomers is the fact that our model class Foggyline_HappyHour_Model_User has absolutely no methods defined other than _construct(), which is not the default PHP construct (__construct()).

So how is it then that the statements such as $user->setLastname('Doe'); work? The answer lies in the derived from the Varien_Object class found in the lib/Varien/Object.php file. One of the things Varien_Object provides is Magento's famous getter and setter methods. If you study the class code, you will see that Magento actually uses the class protected $_data property internally via the help of PHP magic methods. Executing $user->setLastname('Doe'); actually sets $_data['username'] = 'Doe';. Or to put it differently, it would virtually create a property named 'úsername' with the value 'Doe' on a $user object instance.

The same logic goes for setting values. Executing a statement such as $user->setData('firstname', 'John'); does almost the same as the previous example.

The difference between the two is that setData() directly changes the value on the protected $_data['username'] property, while setLastname('Doe'); will first try to look for the setLastname() method within the Foggyline_HappyHour_Model_User class. If the method is found, the value is passed to the method and the method is in charge of passing the value to the protected $_data['username'] property, possibly doing some modifications on it.

You should take some time to study the inner workings of the Varien_Object class, as it is the base class for all of your models.

To continue with our preceding example, if you now try to open the URL http://magento1702ce.loc/index.php/happyhour/hello/testUserSave in your browser, you should be able to see the Successfully saved user message.

Once you confirm that the entity save action is working, you should test and confirm that the model collection is working too. Create a new action under the Foggyline_HappyHour_HelloController class as follows:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{
   /* … other code … */  
   public function testUserCollectionAction()
   {
      $users = Mage::getModel('foggyline_happyhour/user')
          ->getCollection();
      
      foreach ($users as $user) {
         $firstname = $user->getFirstname();
         /* or: $user->getData('firstname') */
         
         $lastname = $user->getLastname();
         /* or: $user->getData('lastname') */
         
         echo "$firstname $lastname<br />";
      }
   }
   /* … other code … */
}

If you now try to open the URL http://magento.loc/index.php/happyhour/hello/testUserCollection in your browser, you should be able to see the list of your users within the foggyline_happyhour_user database table.

If you were able to follow up and all went well, you should now have a fully working model entity. There is a lot more to be said about models; however, this is enough to get you started.

Next, we will move on to an event/observer pattern implemented by Magento. Events and observers are extremely important in Magento because they enable you to easily hook onto various parts of Magento and add your own pieces of code to it. In certain situations they are slightly underestimated by extension developers, either due to their knowledge of the platform, or due to the lack of grand vision or forced quick and dirty implementations.

Events and observers are the key to writing unobtrusive code in cases where you need to change or add to the default Magento behavior. For example, if you need to send all your newly created orders to an external fulfillment system, most of the time you simply need to observe a proper event and implement your business logic within an observer.

There are several types of events getting fired in Magento depending on how you differentiate them. For example, we could divide them into static and dynamic events.

Static events are all those events defined through code with full event names such as Mage::dispatchEvent('admin_session_user_login_failed', array('user_name' => $username, 'exception' => $e));, Mage::dispatchEvent('cms_page_prepare_save', array('page' => $model, 'request' => $this->getRequest()));, Mage::dispatchEvent('catalog_product_get_final_price', array('product' => $product, 'qty' => $qty));, Mage::dispatchEvent('catalog_product_flat_prepare_columns', array('columns' => $columnsObject));, and Mage::dispatchEvent('catalog_prepare_price_select', $eventArgs);.

Dynamic events are all those events defined through code dynamically at runtime such as Mage::dispatchEvent($this->_eventPrefix.'_load_before', $params);, Mage::dispatchEvent($this->_eventPrefix.'_load_after', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_save_before', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_save_after', $this->_getEventData());, and Mage::dispatchEvent('controller_action_layout_render_before_'.$this->getFullActionName());.

Both types of events are absolutely the same; they function the same, and the preceding differentiation is simply a matter of terminology. We are calling the other ones dynamic because their full name is not known until the runtime.

For example, each time you wish to intercept certain parameters passed to a controller action, you could simply create an event observer that would observe the controller_action_predispatch_* event, which is triggered within the Mage_Core_Controller_Varien_Action class file as follows: Mage::dispatchEvent('controller_action_predispatch_' . $this->getFullActionName(), array('controller_action' => $this));.

Now, let us see how exactly do we define the event observer and place some of our code to be executed upon certain events. First, we need to create an entry within our extensions config.xml file.

Let's say we want to introspect all the parameters passed to the controller action during the customer registration process. When a customer fills in the required registration fields and clicks on Submit, the form posts the data to the http://{{shop.domain}}/index.php/customer/account/createpost/ URL.

If you look at the previously mentioned the controller_action_predispatch_* event, the expression $this->getFullActionName() would return the customer_account_createpost string. You can find that out easily by placing the var_dump($this->getFullActionName()); exit; expression right there under the Mage::dispatchEvent('controller_action_predispatch_... expression. Please note that we are using var_dump here just for the simplicity of demonstration. So now that we know this, we can safely conclude that the full event name we need to observe in this case is controller_action_predispatch_customer_account_createpost.

Now we know that the event name is a requirement upon which we create a proper config.xml entry for defining our event observer as shown in the following code:

<?xml version="1.0"?>
<config>
   <!-- … other elements ... -->
   <frontend>
      <events>
         <controller_action_predispatch_customer_account_createpost>
            <observers>
              <foggyline_happyhour_intercept>
                 <class>foggyline_happyhour/observerobserver</class>
                 <method>intercept</method>
                 </foggyline_happyhour_intercept>
              </observers>
         </controller_action_predispatch_customer_account_createpost>
      </events>
   </frontend>
   <!-- … other elements ... -->
</config>

Within the observer's element comes the definition of our observer, which we call foggyline_happyhour_intercept in this case. Each observer needs two properties-defined classes, which in this case points to the foggyline_happyhour class group and Observer class file thus, the string foggyline_happyhour/observer; the other one is the method within the Observer class file.

Next, we create the actual Observer class file app/code/community/Foggyline/HappyHour/Model/Observer.php with the following content:

<?php

class Foggyline_HappyHour_Model_Observer
{
   public function intercept($observer = null)
   {
      $event = $observer->getEvent();
      $controllerAction = $event->getControllerAction();
      $params = $controllerAction->getRequest()->getParams();
      
      Mage::log($params);
   }
}

A quick look at Foggyline_HappyHour_Model_Observer reveals one important thing: unlike Model, Block, and Controller classes, the Observer classes do not need to extend anything.

If you now go to your browser and try to create a new customer account, you will get your var/log/system.log file filled with the HTTP POST parameters provided by the customer during the registration process. You might need to refresh/re-open system.log in your editor in order to pick up the changes, in case you don't see the log entries.

Sometimes, the right event might not be there; so you might need to look for the second best. For example, if we did not have the controller_action_predispatch_customer_account_createpost event dispatched, the next best event would probably be the following one: Mage::dispatchEvent('controller_action_predispatch', array('controller_action' => $this));.

However, the event controller_action_predispatch is pretty generic, which means it will get triggered for every controller action predispatch. In this case, you would have to do a little if/else logic within your event observer code. Just as we have controller fired events, we also have model-fired events. If you open a class file like Mage_Catalog_Model_Product, you can see property definitions like protected $_eventPrefix = 'catalog_product'; and protected $_eventObject = 'product';.

Now, if you trace the code a little bit down to the Mage_Core_Model_Abstract class file, you will see that the properties $_eventPrefix and $_eventObject are used for dynamic events such as (along with the static events for the same action) Mage::dispatchEvent($this->_eventPrefix.'_load_before', $params);, Mage::dispatchEvent($this->_eventPrefix.'_load_after', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_save_commit_after', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_save_before', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_save_after', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_delete_before', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_delete_after', $this->_getEventData());, Mage::dispatchEvent($this->_eventPrefix.'_delete_commit_after', $this->_getEventData());, and Mage::dispatchEvent($this->_eventPrefix.'_clear', $this->_getEventData());.

Knowing this is extremely important, as it enables you to create all sorts of event observers for specific models and their actions, for example customer, order, and invoice entity create/update/delete actions. This is why defining the $_eventPrefix and $_eventObject properties on your custom model classes is something you should adopt as a sign of good coding practice. Doing so enables other third-party developers to easily hook onto your extension code via the observer in a clean and unobtrusive way.

Cron jobs are used to schedule commands to be executed periodically by the cron. Cron is a a time-based job scheduler software in Unix-like computer operating systems. It is driven by a crontab (cron table) file, a configuration file that specifies shell commands to run periodically on a given schedule.

Magento cron jobs is a different kind of functionality than that just mentioned. It merely relies on the system cron software to trigger the root Magento cron.php or cron.sh files periodically. Keep that in mind while talking about cron and Magento cron jobs.

It is highly important that the system administrator has the system cron set to trigger the Magento cron.sh file at regular intervals, at least every five minutes. This can be done by adding the following line to system cron:*/5 * * * * /path/to /magento/root/folder/cron.sh. This way, you as a Magento extension developer have the ability to create a new Magento cron jobs definitions through your extensions configuration files and rest assured they will get executed. Magento cron jobs are defined in the config.xml file as follows:

<?xml version="1.0"?>
<config>
<!-- … other elements ... -->
   <crontab>
      <jobs>
         <foggyline_happyhour_ordersToFulfilment>
            <schedule>
               <cron_expr>*/2 * * * *</cron_expr>
            </schedule>
            <run>
               <model>foggyline_happyhour/service::ordersToFulfilment</model>
            </run>
         </foggyline_happyhour_ordersToFulfilment>
      </jobs>
   </crontab>   
<!-- … other elements ... -->
</config>

In this example, our cron job has been defined with the name foggyline_happyhour_ordersToFulfilment and set to execute every two minutes, which can be seen by the schedule >cron_expr value. For more details on writing cron expressions, check out the following URL: http://en.wikipedia.org/wiki/Cron.

The model element, which in this case is set to foggyline_happyhour/service::ordersToFulfilment, means that the following code from the app/code/community/Foggyline/HappyHour/Model/Service.php file would get executed by this cron job:

<?php

class Foggyline_HappyHour_Model_Service
{
   public function ping() 
   {
      Mage::log('ping');
   }
}

The same as with observer classes, cron-defined model classes do not need to extend anything.

Even though this Magento cron job has been set to run every two minutes, you as an extension developer have no guarantee that the system cron will ever be run on a third-party website, or if it's run it might not be run in small enough intervals. Thus, you might end up with a code logic that never gets executed, or gets executed in larger than planned intervals.

During development, however, you do not need to have the system cron set up. It is sufficient to just execute the http://magento.loc/cron.php URL in the browser, as this will trigger the Magento cron system.

For example, if you were writing an extension that has one or more Magento cron jobs defined in config.xml, the easiest way to check if you correctly defined your cron job would be to truncate the cron_schedule database table and then trigger the http://magento.loc/cron.php URL in the browser. Obviously, in this case, later on you would have to periodically trigger the http://magento.loc/cron.php URL to check if your cron job execution went through, monitoring the executed_at column within the cron_schedule database table.

There is one part of Magento functionality that gets equally used across all the individual functionality mentioned so far, and that's helpers. Magento helper is a class that usually extends the Mage_Core_Helper_Data class directly found in the app/code/core/Mage/Core/Helper/Data.php file or at the very least derived from the Mage_Core_Helper_Abstract class found under the app/code/core/Mage/Core/Helper/Abstract.php file.

The Helper classes contain various utility methods that will allow you to perform common tasks on different objects and variables. Helpers too are defined via the config.xml elements as follows:

<?xml version="1.0"?>
<config>
   <!-- … other elements ... -->
   <global>
      <helpers>
         <foggyline_happyhour>
            <class>Foggyline_HappyHour_Helper</class>
         </foggyline_happyhour>
      </helpers>
   </global>
   <!-- … other elements ... -->
</config>

Similar to blocks and models, helpers have a class element defined to point to their folder locations within an extension. In this example, a helper is defined with the name foggyline_happyhour.

As you are allowed to have multiple helpers under the app/code/community/Foggyline/HappyHour/Helper/ folder, it is important to know that the default helper PHP filename is Data.php.

What this really means is that when you execute a statement such as Mage::helper('foggyline_happyhour');, Magento will load the Data.php helper. If, however, you execute a statement such as Mage::helper('foggyline_happyhour/image');, Magento will load the Image.php helper (the app/code/community/Foggyline/HappyHour/Helper/Image.php file).

Besides being a utility method container, the Helper classes play an indispensable role for extensions that provide Magento-style configuration options for users. For example, if you were building a payment extension, you would most certainly need a configuration area in order to set up the access data for it. Magento comes with its own built-in configuration area, located under System | Configuration. This entire section is built from the XML elements found under the extension etc/system.xml.

Here is where things get a little complicated. In order for the Magento admin user to have access to your extension configuration interface defined through system.xml, it needs permissions for that. These permissions are defined in another configuration file located in the same folder called adminhtml.xml.

Let us demonstrate this with a simple example. We will create a configuration options section for our extension within system.xml, define permissions to it via adminhtml.xml, and then use the data helper class to fetch that configuration value from within our controller.

First, we need to create the app/code/community/Foggyline/HappyHour/etc/system.xml configuration file with the following content:

<?xml version="1.0"?>
<config>
   <tabs>
      <foggyline module="foggyline_happyhour">">
         <label>Foggyline</label>
        <sort_order>10</sort_order>
      </foggyline>
   </tabs>
   <sections>
      <foggyline_happyhour module="foggyline_happyhour">
         <label>FoggylineHappyHour</label>
         <tab>foggyline</tab>
         <sort_order>10</sort_order>
         <show_in_default>1</show_in_default>
         <groups>
            <settings>
               <label>FoggylineHappyHour Settings</label>
               <sort_order>10</sort_order>
               <show_in_default>1</show_in_default>
               <fields>
                  <custom_message>
                     <label>Custom Message</label>
                     <frontend_type>text</frontend_type>
                     <sort_order>20</sort_order>
                     <show_in_default>1</show_in_default>
                  </custom_message>
               </fields>
            </settings>
         </groups>
      </foggyline_happyhour>
   </sections>
</config>

The first thing that we did was add a custom tab called Foggyline to the system configuration. Tabs are the navigation headers down the left-hand side of the Magento administration are a under System | Configuration. The default tabs are General, Catalog, Customers, Sales, Services, and Advanced. Adding a new tab is as simple as defining your own element under Configuration | Tabs. In our example, we have defined the foggyline element, where foggyline is a freely given element name. The attribute module="foggyline_happyhour" simply tells Magento what helper to use for this part of functionality while referencing helpers internally. The string foggyline_happyhour points to the helper group defined under config.xml. The label element specifies the label for this tab to be shown under the navigation sidebar. The sort_order element specifies the order in the sidebar with regards to other elements; a larger number pushes the item in the sidebar to the bottom after other elements.

Once we have defined the actual tab, we need to add one or more sections to it. In our example, we have defined one section through the foggyline_happyhour element.

The foggyline_happyhour element is an arbitrary name that's used to identify your new section.

The label element defines the display value used in the HTML interface for your new section.

The tab element identifies which tab your new section should be grouped under. We want our section to show up under our new Foggyline tab. The name foggyline comes from the tag used to create the Foggyline tab.

The sort_order element determines where this section shows up vertically compared to other sections in the tab.

The show_in_default element is a Boolean configuration option with a valid value of 1 or 0. They determine the level of configuration scope this section has.

The groups element determines the logical grouping of configuration options, sort of like the fieldset element in HTML forms.

The settings element within groups is an arbitrary name that's used to identify this group.

The elements label, sort_order, and show_in_default are analogous to those previously explained for this section.

The fields element is a container for one or more elements that will be visually manifested into HTML form elements later. Within the fields element, again we have label, sort_order, show_in_default, and this time one new element called frontend_type. The frontend_type element determines what HTML element will be used for rendering in the browser.

At this point if you try to log in to Magento and navigate to System | Configuration, you will be able to see the FoggylineHappyHour menu in the left sidebar. However, accessing the menu item would give you a 404 Error Page not found error.

This might be a good time to explain what ACL actually is. ACL, short for Access Control Lists, is a functionality that allows a store owner to create fine-grained roles for each and every user in their system. A default Magento installation comes with one role, Administrators. Magento ACL implementation allows you to add new roles to the system via System | Permissions | Roles. A role is essentially a collection of resources, while a resource is basically an action such as "delete user".

While adding new system configuration sections, you need to define resources for it so that Magento can use it via its ACL system. So the reason why we might be getting a 404 Error Page not found error is that we are missing the ACL definition.

This is why we need to create the app/code/community/Foggyline/HappyHour/etc/adminhtml.xml file with the following content:

<?xml version="1.0"?>
<config>
   <acl>
      <resources>
         <admin>
            <children>
               <system>
                  <children>
                     <config>
                        <children>
                           <foggyline_happyhour module="foggyline_happyhour">">
                              <title>FoggylineHappyHour</title>
                           </foggyline_happyhour>
                        </children>
                     </config>
                  </children>
               </system>
            </children>
         </admin>
      </resources>
   </acl>
</config>

Once done, you need to log out and then log back in to Magento administration in order for acl (access list) to kick in, otherwise you will still be getting a 404 Error Page not found error when you try to access System | Configuration | Foggyline | FoggylineHappyHour.

Now get back to the adminhtml.xml file. The syntax of the file seems somewhat recursive with all those children elements repeating. We could say that we need to define a resource whose path matches the system configuration option defined under system.xml. So if a base path for the acl resource within adminhtml.xml is config > acl > resources > admin > children > system > children > config > children, we simply need to define a new child within it called foggyline_happyhour like we did in the preceding example. The element name foggyline_happyhour must match the element name of the section from within system.xml.

The title element simply dictates what will show up in the Magento administration panel when the node tree is displayed.

If all went well, you should be able to see your configuration options interface as shown in the following screenshot:

Magento allows each configuration option defined through system.xml to have a default value. For example, let's say we want the default value of our custom_message to be Hello World string. To do so, we turn to our config.xml file as follows:

<?xml version="1.0"?>
<config>
   <!-- … other elements ... -->
   <default>
      <foggyline_happyhour>
         <settings>
            <custom_message><![CDATA[Hello World]]></custom_message>
         </settings>
      </foggyline_happyhour>
   </default>
   <!-- … other elements ... -->
</config>

It might look a bit confusing at first, but notice how the config.xml element paths within the default element path foggyline_happyhour> settings >foggyline_happyhour follow the system.xml element paths within the sections element path foggyline_happyhour> settings > foggyline_happyhour (minus the groups element). Now if you open the System | Configuration | Foggyline | FoggylineHappyHour, you should see, if you haven't previously saved some other value, the text Hello World under the Custom Message option value.

Finally, as shown in the following code snippet, we will use the helper Data class to add utility methods for extracting our configuration option value from the system.xml:

<?php

class Foggyline_HappyHour_Helper_Data extends Mage_Core_Helper_Data
{
   const XML_PATH_CUSTOM_MESSAGE = 'foggyline_happyhour/settings/custom_message';
   
   public function getCustomMessage($storestore = null)
   {
      return Mage::getStoreConfig(self::XML_PATH_CUSTOM_MESSAGE, $store);
   }
}

Looking at the preceding code, it is easy to conclude how the const XML_PATH_CUSTOM_MESSAGE string value follows the same XML elements path as previously mentioned for system.xml and config.xml. Passing that string to Mage::getStoreConfig() will retrieve our custom message.

To confirm everything is working, add the following action to your app/code/community/Foggyline/HappyHour/controllers/HelloController.php class file:

<?php

class Foggyline_HappyHour_HelloController extends Mage_Core_Controller_Front_Action
{   
   public function helperTestAction()
   {
      echo Mage::helper('foggyline_happyhour')->getCustomMessage();
   }
}

Now open the http://magento.loc/index.php/happyhour/hello/helperTest URL in the browser; if all is good, you should be able to see the Hello World message.

Even though we have covered a lot of ground so far, we have barely scratched the surface. The massiveness of the Magento platform hides far more features. These, however, are left for you to discover.

Magento is known for its poor developer documentation regarding certain features. Every now and then you will find yourself tracing the Magento core code trying to understand its inner workings. Hopefully, the preceding introduction will give you a good starting point.

Up until now, we have covered the basics of Magento's overall structure. We took a dive into the extension structure itself. As we progressed through individual extension structures, we familiarized ourselves with configuration file, Model, Block, Helper, controller classes, and a few other important concepts. We gave a brief intro to the Magento event/observer pattern, cron jobs functionality, and access lists. With this combined knowledge, we should now be ready for the next chapter, the full-blown extension.