Advice for new Magento developers

Magento is a popular and growing e-commerce solution which provides an end-to-end interface for merchants and customers alike.  After a simple installation process Magento enables merchants to create their products, integrate with popular payment and shipment providers, provide coupon codes, and track reports. On the customer side customers can create accounts to track their purchases, earn rewards points, create wishlists, and invite friends to join the site.  However, as simple in presentation as Magento may be, what happens behind the scenes is extremely complex in application.  As difficult as it is to master the Magento codebase, it is vastly outweighed by the challenge of training developers who have never been exposed to it before.

Magento is extremely powerful from an architectural perspective, but like any complex system there are numerous rules that must be followed in order to maximize its potential.  One of the biggest problems with Magento is not following these rules, but figuring out all of the rules in the first place.  Magento contains modules, blocks, helpers, controllers, configuration files, models, layouts, templates and code pools, all of which follow their own subset of rules and must work seamlessly together. Once a new developer has been exposed to and received explanations for these, the challenge of implementing this knowledge in practice emerges.

Perhaps the most important concept to explain to new developers is to never modify a core Magento file.  The reasoning behind this is that if you ever upgrade your Magento version, all changes to core files will be lost.  This applies to both default PHP, PHTML, and XML files.  There are many ways to change a core file – there are different ways to overwrite different file types.  Most core Magento blocks, models, and helpers can all be rewritten to a custom module with a small piece of XML code in the module’s configuration file.  However, this logic cannot be applied to some of these files, only enhancing the confusion for new engineers.  For example, abstract classes cannot be rewritten to custom Magento modules.  In order to change an abstract class a developer must following the simplest method for rewriting core Magento files.  This is done by copying the file structure in


to app/code/local/Mage/<module>/<file_path>.

Magento by default looks for its PHP files in directories by the following order:

app/code/local, app/code/community/, app/code/core, and lib/.

Controllers are the most difficult class type to overwrite as they cannot be written using the same technique for blocks / helpers / models nor can they be accessed by simply moving them from the app/code/core to the app/code/local folder.

Design files, which include the template .phtml and layout .xml files, follow a separate methodology for making changes without modifying core files.  By default Magento looks for its front-end files in


and app/design/frontend/base/default/layout,

where base is the package and default is the theme. The Magento admin section allows the default package and theme to be changed so that it will search for its design files in the specified package and theme before looking anywhere else.  So if I specify my default package to pixafy and my default theme to training, Magento will look for its design files in app/design/frontend/pixafy/training rather than app/design/frontend/base/default.  One great aspect of this architecture is that if Magento cannot find a template or layout file in the package and theme you specify, it will automatically fall back to the base/default package and theme. This allows developers to only move over the files they need to change instead of the entire base/default directory.

Developers who are beginning to work within Magento have a wide range of reactions to these case-specific implementations.  While all engineers I have trained require at least a few weeks to understand these rules, some react well while others are completely intimidated.  It is very tempting (and time-saving) in the short run to simply open up a Magento core file and make any changes that need to be made.  Those who take this approach to programming Magento learn the hard way that any time saved will ultimately be lost when the site is upgraded and a feature they spent hours implementing is completely lost.

My advice to new Magento developers is to always follow the proper Magento guidelines for making code changes.  It is absolutely not worth the couple of minutes that are saved side-stepping these rules when something goes wrong and you’re endlessly search Magento’s thousands of core files to replace that one line of code.  If you always follow Magento’s guidelines for making changes it can be a very powerful and beneficial development tool.  On the other hand, if you “hack” Magento’s files to save some time, you will experience numerous headaches when try to fix any issues that occur.