Magento PHP Developer????s Guide, 2nd Edition

As you probably know, Magento is the most powerful e-commerce platform in the market. What you might not know about Magento is that it is also an object-oriented (OO) PHP framework developed on top of Zend Framework.

Here's how Zend's official site describes the framework:

What exactly is Zend Framework? Zend Framework is an OO framework developed on PHP that implements the Model-View-Controller (MVC) paradigm. When Varien (now Magento Inc.) started developing Magento, they decided to do it on top of Zend because of some components, some of which are as follows:

In total, Magento uses around 15 different Zend components. The Varien library extends several of the Zend components mentioned before directly. For example, Varien_Cache_Core extends from Zend_Cache_Core.

Using Zend Framework, Magento was built with the following principles in mind:

Although experience of using Zend Framework or even understanding it are not requirements to develop Magento, having at least some basic understanding of the Zend components, usage, and interaction can be invaluable information as we start digging deeper into the core of Magento.

You can learn more about Zend Framework at http://framework.zend.com/.

The Magento folder structure is slightly different from other MVC applications. Let's take a look at the directory tree, and each directory and its functions:

Magento is a modular system. This means the application, including the core, is divided into smaller modules. For this reason, the folder structure plays a key role in the organization of each module. A typical Magento module folder structure would look something like this:

Let's review each folder further:

As we will see later in this chapter, Magento makes heavy use of factory names and factory methods. This is why the folder structure is so important.

Rather than being a large application, Magento is built by smaller modules, each adding specific functionality to Magento.

One of the advantages of this approach is the ability to enable and disable specific module functionality with ease as well as adding new functionality by adding new modules.

… 
Mage::register('original_include_path', get_include_path());
if (defined('COMPILER_INCLUDE_PATH')) {
    $appPath = COMPILER_INCLUDE_PATH;
    set_include_path($appPath . PS . Mage::registry('original_include_path'));
    include_once "Mage_Core_functions.php";
    include_once "Varien_Autoload.php";
} else {
    /**
     * Set include path
     */
    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'local';
    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'community';
    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'core';
    $paths[] = BP . DS . 'lib';

    $appPath = implode(PS, $paths);
    set_include_path($appPath . PS . Mage::registry('original_include_path'));
    include_once "Mage/Core/functions.php";
    include_once "Varien/Autoload.php";
}

Varien_Autoload::register();

    /**
     * Load class source code
     *
     * @param string $class
     */
    public function autoload($class)
    {
        if ($this->_collectClasses) {
            $this->_arrLoadedClasses[self::$_scope][] = $class;
        }
        if ($this->_isIncludePathDefined) {
            $classFile =  COMPILER_INCLUDE_PATH . DIRECTORY_SEPARATOR . $class;
        } else {
            $classFile = str_replace(' ', DIRECTORY_SEPARATOR, ucwords(str_replace('_', ' ', $class)));
        }
        $classFile.= '.php';
        //echo $classFile;die();
        return include $classFile;
    }

    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'local';
    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'community';
    $paths[] = BP . DS . 'app' . DS . 'code' . DS . 'core';
    $paths[] = BP . DS . 'lib';

Before going into more detail about the different components that form a part of Magento, it is important that we understand how these components interact together and how Magento processes requests coming from the web server.

As with any other PHP application, we have a single file as an entry point for every request. In the case of Magento, this file is index.php, which is in charge of loading the Mage.php Bootstrap class and starting the request cycle.

Routers are especially important in this process. Router objects are used by the frontend controller to match a requested URL (route) to a module controller and action. By default, Magento comes with the following routers:

The action controller will then load and render the layout, which in turn will load the corresponding blocks, models, and templates.

Let's analyze how Magento will handle a request to a category page. We will use http://localhost/catalog/category/view/id/10 as an example. The Magento URI comprises three parts, namely FrontName/ControllerName/ActionName.

Hence, for our example URL, the breakdown is as follows:

Let's take a look at the Magento router class Mage_Core_Controller_Varien_Router_Standard match function:

public function match(Zend_Controller_Request_Http $request)
{
  …
   $path = trim($request->getPathInfo(), '/');
            if ($path) {
                $p = explode('/', $path);
            } else {
                $p = explode('/', $this->_getDefaultPath());
            }
  …
}

From the previous code, we can see that the first thing the router tries to do is parse the URI into an array. Based on our example URL, the corresponding array will be similar to the following code:

$p = Array
(
    [0] => catalog
    [1] => category
    [2] => view
)

The next part of the function will first try to check if the request has the module name specified. If not, then it tries to determine the module name, based on the first element of our array. If a module name can't be provided, then the function will return false. Let's take a look at this part of the code:

      // get module name
        if ($request->getModuleName()) {
            $module = $request->getModuleName();
        } else {
            if (!empty($p[0])) {
                $module = $p[0];
            } else {
                $module = $this->getFront()->getDefault('module');
                $request->setAlias(Mage_Core_Model_Url_Rewrite::REWRITE_REQUEST_PATH_ALIAS, '');
            }
        }
        if (!$module) {
            if (Mage::app()->getStore()->isAdmin()) {
                $module = 'admin';
            } else {
                return false;
            }
        }

Next, the match function will iterate through each of the available modules and try to match the controller and action using the following code:

…
        foreach ($modules as $realModule) {
            $request->setRouteName($this->getRouteByFrontName($module));

            // get controller name
            if ($request->getControllerName()) {
                $controller = $request->getControllerName();
            } else {
                if (!empty($p[1])) {
                    $controller = $p[1];
                } else {
                    $controller = $front->getDefault('controller');
                    $request->setAlias(
                        Mage_Core_Model_Url_Rewrite::REWRITE_REQUEST_PATH_ALIAS,
                        ltrim($request->getOriginalPathInfo(), '/')
                    );
                }
            }

            // get action name
            if (empty($action)) {
                if ($request->getActionName()) {
                    $action = $request->getActionName();
                } else {
                    $action = !empty($p[2]) ? $p[2] : $front->getDefault('action');
                }
            }

            //checking if this place should be secure
            $this->_checkShouldBeSecure($request, '/'.$module.'/'.$controller.'/'.$action);

            $controllerClassName = $this->_validateControllerClassName($realModule, $controller);
            if (!$controllerClassName) {
                continue;
            }

            // instantiate controller class
            $controllerInstance = Mage::getControllerInstance($controllerClassName, $request, $front->getResponse());

            if (!$controllerInstance->hasAction($action)) {
                continue;
            }

            $found = true;
            break;
        }
...

Now that looks like an awful lot of code! Let's break it down further. The first part of the loop will check if the request has a controller name. If it is not set, it will check our parameter array's ($p) second value and try to determine the controller name. Then, it will try to do the same for the action name.

If we get this far in the loop, we should have a module name, a controller name, and an action name. Magento will now use these to try and get matched with the Controller class name by calling the following code:

$controllerClassName = $this->_validateControllerClassName($realModule, $controller);

This function will not only generate a matching class name, but it will also validate its existence. In our example case, this function should return Mage_Catalog_CategoryController.

As we now have a valid class name, we can proceed to instantiate our controller object. You may probably notice that so far we haven't done anything with our action yet, and that's precisely the next step on our loop.

Now, our instantiated controller comes with a very handy function called hasAction(). In essence, all this function does is call a PHP function called is_callable(), which will check if our current controller has a public function matching the action name. In our case this will be viewAction().

The reason behind this elaborate matching process and the use of a foreach loop is that it is possible for several modules to use the same frontName:

Now, http://localhost/catalog/category/view/id/10 is not a very user-friendly URL. Fortunately, Magento has its own URL rewrite system that allows us to use http://localhost/books.html.

Let's dig a little deeper into the URL rewrite system and see how Magento gets the controller and action names from our URL alias. Inside our Varien/Front.php controller dispatch function, Magento will call the following action:

Mage::getModel('core/url_rewrite')->rewrite();

Before actually looking into the inner working of the rewrite function, let's take a look at the structure of the core/url_rewrite model:

Array (
  ["url_rewrite_id"] => "10"
  ["store_id"]       => "1"
  ["category_id"]    => "10"
  ["product_id"]     => NULL
  ["id_path"]        => "category/10"
  ["request_path"]   => "books.html"
  ["target_path"]    => "catalog/category/view/id/10"
  ["is_system"]      => "1"
  ["options"]        => NULL
  ["description"]    => NULL
)

As we can see, the rewrite module comprises several properties, but only two of them are of particular interest to us, namely request_path and target_path. Simply put, the job of the rewrite module is to modify the request object path information with the matching values of target_path.

If you are familiar with traditional MVC implementations such as CakePHP or Symfony, you may know that the most common implementation is called a convention-based MVC. With a convention-based MVC to add a new Model, or let's say a Controller, you only need to create the file/class (following the framework conventions); the system will pick it up automatically.

Magento on the other hand uses a configuration-based MVC pattern, which means creating our file/class is not enough; we have to tell Magento explicitly that we have added a new class using configuration files written in XML.

Each Magento module has a config.xml file that is located under the module's etc/ directory and contains all the relevant module configurations. For example, if we want to add a new module that includes a new model, we need to define a node in the configuration file that tells Magento where to find our model. Here's an example:

<global>
…
<models>
     <group_classname>
          <class>Namespace_Modulename_Model</class>
     <group_classname>
</models>
...
</global>

Although this might look like additional work, it also gives us a huge amount of flexibility and power. For example, we can rewrite another class by using the rewrite node:

<global>
…
<models>
     <modulenamemodulename>
      <rewrite>
             <groupgroup_classname>Namespace_Modulename_Model</groupgroup_classname>
      </rewrite>
     <//modulename>
</models>
...
</global>

Magento will then load all the config.xml files and merge them at runtime, creating a single configuration tree.

Additionally, modules can also have a system.xml file that is used to specify configuration options in the Magento backend, which end users can in turn use to configure the module functionality. A snippet of a system.xml file will look like this:

<config>
  <sections>
    <section_name translate="label">
      <label>Section Description</label>
      <tab>general</tab>
      <frontend_type>text</frontend_type>
      <sort_order>1000</sort_order>
      <show_in_default>1</show_in_default>
      <show_in_website>1</show_in_website>
      <show_in_store>1</show_in_store>
      <groups>
       <group_name translate="label">
         <label>Demo Of Config Fields</label>
         <frontend_type>text</frontend_type>
         <sort_order>1</sort_order>
         <show_in_default>1</show_in_default>
         <show_in_website>1</show_in_website>
         <show_in_store>1</show_in_store>  
   <fields>
          <field_name translate="label comment">
             <label>Enabled</label>
             <comment>
               <![CDATA[Comments can contain <strong>HTML</strong>]]>
             </comment>
             <frontend_type>select</frontend_type>
             <source_model>adminhtml/system_config_source_yesno</source_model>
             <sort_order>10</sort_order>
             <show_in_default>1</show_in_default>
             <show_in_website>1</show_in_website>
             <show_in_store>1</show_in_store>
          </field_name>
         </fields>
        </group_name>
       </groups>
    </section_name>
  </sections>
</config>

Let's break down each node function:

Just by using XML, we can build complex configuration options for our modules right on the Magento backend without having to worry about setting up templates, populating fields, or validating data.

Magento is also kind enough to provide a comprehensive amount of form field validation models that we can use with the <validate> tag. Among the field validators we have the following options:

As with any other part of Magento, we can extend source_models, frontend_types, and validators, and even create new ones. We will be tackling this task in a later chapter, where we will create a new type of each. For now, we will explore the concepts of models, views, file layouts, and controllers.

Dissecting a layout file

Let's examine one of the Magento core layout files, in this case, the catalog.xml file:

<layout version="0.1.0">
<default>
    <reference name="left">
        <block type="core/template" name="left.permanent.callout" template="callouts/left_col.phtml">
            <action method="setImgSrc"><src>images/media/col_left_callout.jpg</src></action>
            <action method="setImgAlt" translate="alt" module="catalog"><alt>Our customer service is available 24/7.Call us at (555) 555-0123.</alt></action>
            <action method="setLinkUrl"><url>checkout/cart</url></action>
        </block>
    </reference>
    <reference name="right">
        <block type="catalog/product_compare_sidebar" before="cart_sidebar" name="catalog.compare.sidebar" template="catalog/product/compare/sidebar.phtml"/>
        <block type="core/template" name="right.permanent.callout" template="callouts/right_col.phtml">
            <action method="setImgSrc"><src>images/media/col_right_callout.jpg</src></action>
            <action method="setImgAlt" translate="alt" module="catalog"><alt>Visit our site and save A LOT!</alt></action>
        </block>
    </reference>
    <reference name="footer_links">
        <action method="addLink" translate="label title" module="catalog" ifconfig="catalog/seo/site_map"><label>Site Map</label><url helper="catalog/map/getCategoryUrl" /><title>Site Map</title></action>
    </reference>
    <block type="catalog/product_price_template" name="catalog_product_price_template" />
</default>

Layout blocks comprise three main XML nodes:

• Handle: Each page request will have several unique handles. The layout uses these handles to tell Magento which blocks to load and render on a per page basis. The most commonly used handles are the default handle and the [frontname]_[controller]_[action] handle.

• The default handle is especially useful to set global blocks, for example, adding CSS or JavaScript to all pages on the header block.

• Reference: A <reference> node is use to make references to a block. It is useful for the specification of nested blocks or modifying an already existing block. In our example, we can see how a new child blocks being specified inside <reference name="left">.

• Block: The <block> node is used to load our actual blocks. Each block node can have the following properties:

  • type: This is the identifier for the actual block class. For example, catalog/product_list makes reference to the Mage_Catalog_Block_Product_List.

  • name: This is the name used by other blocks to make a reference to this block.

  • before/after: These properties can be used to position the blocks relative to other block position. Both properties can use a hyphen as value to specify if the module should appear at the very top or the very bottom.

  • template: This property determines the .phtml template file that will be used to render the block.

  • action: Each block type has specific actions that affect the frontend functionality. For instance, the page/html_head block has actions to add CSS and js (addJs and addCss).

  • as: This is used to specify the unique identifier that we will be using to call the block from the template. For example, calling a child block by using getChildHtml('block_name').

Blocks are a new concept that Magento implements in order to reduce the controller load. They are basically data resources that communicate directly with the models that manipulate the data if needed and then pass it to the views.

Finally, we have our .phtml files. Templates contain HTML and PHP tags and are in charge of formatting and displaying the data from our models. Let's take a look at a snippet from the product view template:

<div class="product-view">
...
    <div class="product-name">
        <h1><?php echo $_helper->productAttribute($_product, $_product->getName(), 'name') ?></h1>
    </div>
...           
    <?php echo $this->getReviewsSummaryHtml($_product, false, true)?>
    <?php echo $this->getChildHtml('alert_urls') ?>
    <?php echo $this->getChildHtml('product_type_data') ?>
    <?php echo $this->getTierPriceHtml() ?>
    <?php echo $this->getChildHtml('extrahint') ?>
...

    <?php if ($_product->getShortDescription()):?>
        <div class="short-description">
            <h2><?php echo $this->__('Quick Overview') ?></h2>
            <div class="std"><?php echo $_helper->productAttribute($_product, nl2br($_product->getShortDescription()), 'short_description') ?></div>
        </div>
    <?php endif;?>
...
</div> 

The following is a diagram displaying the MVC model:

    public function viewAction()
    {
        $this->loadLayout();
        $this->renderLayout();
    }

One of Magento's core features is the ability to handle multiple websites and stores with a single Magento installation. Internally, Magento refers to each of these instances as scopes.

Values for certain elements such as products, categories, attributes, and configuration are scope-specific and can differ on different scopes. This gives Magento tremendous flexibility. For example, a product can be set up on two different websites with different prices but still share the rest of the attribute configuration.

As developers, one of the areas where we will be using scopes the most is when working with configuration. The different configuration scopes available in Magento are as follows:

Configuration options in Magento can store values on three scopes (global, website, and store views). By default, all the values are set on the global scope. Using system.xml on our modules, we can specify the scopes on which the configuration options can be set. Let's revisit our previous system.xml file:

…
<field_name translate="label comment">
    <label>Enabled</label>
    <comment>
         <![CDATA[Comments can contain <strong>HTML</strong>]]>
     </comment>
     <frontend_type>select</frontend_type>
     <source_model>adminhtml/system_config_source_yesno</source_model>
     <sort_order>10</sort_order>
     <show_in_default>1</show_in_default>
     <show_in_website>1</show_in_website>
     <show_in_store>1</show_in_store>
</field_name>
…

Magento makes use of factory methods to instantiate models, helpers, and block classes. A factory method is a design pattern that allows us to instantiate an object without using the exact class name and using a class alias instead.

Magento implements the following factory methods:

Each of these methods takes a class alias that is used to determine the real class name of the object that we are trying to instantiate. For example, if we want to instantiate a product object, we can do so by calling the getModel() method:

$product = Mage::getModel('catalog/product'); 

Notice that we are passing a factory name composed of group_classname/model_name. Magento will resolve this to the actual class name of Mage_Catalog_Model_Product. Let's take a closer look at the inner workings of getModel():

public static function getModel($modelClass = '', $arguments = array())
    {
        return self::getConfig()->getModelInstance($modelClass, $arguments);
    }

getModel calls the getModelInstance from the Mage_Core_Model_Config class.

public function getModelInstance($modelClass='', $constructArguments=array())
{
    $className = $this->getModelClassName($modelClass);
    if (class_exists($className)) {
        Varien_Profiler::start('CORE::create_object_of::'.$className);
        $obj = new $className($constructArguments);
        Varien_Profiler::stop('CORE::create_object_of::'.$className);
        return $obj;
    } else {
        return false;
    }
}

In return, getModelInstance() calls the getModelClassName() method that takes a class alias as a parameter. Then, it tries to validate the existence of the returned class, and if the class exists, it creates a new instance of that class and returns it to our getModel() method:

public function getModelClassName($modelClass)
{
    $modelClass = trim($modelClass);
    if (strpos($modelClass, '/')===false) {
        return $modelClass;
    }
    return $this->getGroupedClassName('model', $modelClass);
}

The getModelClassName() method calls the getGroupedClassName() method, which is actually in charge of returning the real class name of our model.

The getGroupedClassName() method takes two parameters, namely $groupType and $classId. The $groupType parameter refers to the type of object that we are trying to instantiate. Currently, only models, blocks, and helpers are supported. The $classId that we are trying to instantiate is as follows:

public function getGroupedClassName($groupType, $classId, $groupRootNode=null)
{
    if (empty($groupRootNode)) {
        $groupRootNode = 'global/'.$groupType.'s';
    }
    $classArr = explode('/', trim($classId));
    $group = $classArr[0];
    $class = !empty($classArr[1]) ? $classArr[1] : null;

    if (isset($this->_classNameCache[$groupRootNode][$group][$class])) {
        return $this->_classNameCache[$groupRootNode][$group][$class];
    }
    $config = $this->_xml->global->{$groupType.'s'}->{$group};
    $className = null;
    if (isset($config->rewrite->$class)) {
        $className = (string)$config->rewrite->$class;
    } else {
        if ($config->deprecatedNode) {
            $deprecatedNode = $config->deprecatedNode;
            $configOld = $this->_xml->global->{$groupType.'s'}->$deprecatedNode;
            if (isset($configOld->rewrite->$class)) {
                $className = (string) $configOld->rewrite->$class;
            }
        }
    }
    if (empty($className)) {
        if (!empty($config)) {
            $className = $config->getClassName();
        }
        if (empty($className)) {
            $className = 'mage_'.$group.'_'.$groupType;
        }
        if (!empty($class)) {
            $className .= '_'.$class;
        }
        $className = uc_words($className);
    }
    $this->_classNameCache[$groupRootNode][$group][$class] = $className;
    return $className;
}

As we can see, getGroupedClassName() is actually doing all the work. It grabs our class alias catalog/product and creates an array by exploding the string on the slash character.

Then, it loads an instance of Varien_Simplexml_Element and passes the first value in our array (group_classname). It also checks if the class has been rewritten, and if it has, we will use the corresponding group name.

Magento also uses a custom version of the uc_words() function that will capitalize the first letters and convert separators of the class alias if needed.

Finally, the function will return the real class name to the getModelInstance() function. In our example case, this will return Mage_Catalog_Model_Product:

The event and observer pattern is probably one of Magento's more interesting features, as it allows developers to extend Magento in critical parts of the application flow.

In order to provide more flexibility and facilitate interaction between the different modules, Magento implements an Event/Observer pattern. This pattern allows modules to be loosely coupled.

There are two parts to this system, an Event dispatch with the object and event information and an Observer listening to a particular event:

protected function _beforeSave()
{
    if (!$this->getId()) {
        $this->isObjectNew(true);
    }
    Mage::dispatchEvent('model_save_before', array('object'=>$this));
    Mage::dispatchEvent($this->_eventPrefix.'_save_before', $this->_getEventData());
    return $this;
}

protected function _afterSave()
{
    $this->cleanModelCache();
    Mage::dispatchEvent('model_save_after', array('object'=>$this));
    Mage::dispatchEvent($this->_eventPrefix.'_save_after', $this->_getEventData());
    return $this;
}

public static function dispatchEvent($name, array $data = array())
{
    $result = self::app()->dispatchEvent($name, $data);
    return $result;
}

public function dispatchEvent($eventName, $args)
{
    foreach ($this->_events as $area=>$events) {
        if (!isset($events[$eventName])) {
            $eventConfig = $this->getConfig()->getEventConfig($area, $eventName);
            if (!$eventConfig) {
                $this->_events[$area][$eventName] = false;
                continue;
            }
            $observers = array();
            foreach ($eventConfig->observers->children() as $obsName=>$obsConfig) {
                $observers[$obsName] = array(
                    'type'  => (string)$obsConfig->type,
                    'model' => $obsConfig->class ? (string)$obsConfig->class : $obsConfig->getClassName(),
                    'method'=> (string)$obsConfig->method,
                    'args'  => (array)$obsConfig->args,
                );
            }
            $events[$eventName]['observers'] = $observers;
            $this->_events[$area][$eventName]['observers'] = $observers;
        }
        if (false===$events[$eventName]) {
            continue;
        } else {
            $event = new Varien_Event($args);
            $event->setName($eventName);
            $observer = new Varien_Event_Observer();
        }

        foreach ($events[$eventName]['observers'] as $obsName=>$obs) {
            $observer->setData(array('event'=>$event));
            Varien_Profiler::start('OBSERVER: '.$obsName);
            switch ($obs['type']) {
                case 'disabled':
                    break;
                case 'object':
                case 'model':
                    $method = $obs['method'];
                    $observer->addData($args);
                    $object = Mage::getModel($obs['model']);
                    $this->_callObserverMethod($object, $method, $observer);
                    break;
                default:
                    $method = $obs['method'];
                    $observer->addData($args);
                    $object = Mage::getSingleton($obs['model']);
                    $this->_callObserverMethod($object, $method, $observer);
                    break;
            }
            Varien_Profiler::stop('OBSERVER: '.$obsName);
        }
    }
    return $this;
}

<events>
    <event_name>
        <observers>
            <observer_identifier>
                <class>module_name/observer</class>
                <method>function_name</method>
            </observer_identifier>
        </observers>
    </event_name>
</events>

class Namespace_Modulename_Model_Observer
{
    public function methodName(Varien_Event_Observer $observer)
    {
        //some code
    }
}

In this chapter, we covered many important and fundamental topics about Magento:

While this may seem overwhelming at first sight, it is just the tip of the iceberg. There is a lot more to learn about each of these topics and Magento. The purpose of this chapter is to make developers aware of all the important components of the platform, from the configuration object to the way the event/object pattern is implemented.

Magento is a powerful and flexible system and much more than an e-commerce platform. The core team has put a lot of effort in making Magento a powerful framework.

In later chapters, we will not only review all these concepts in more detail, but we will also apply them in a practical manner by building our own extensions.