Introduction

This isn’t a tutorial. This is a (debatable) list of things I think you should be doing as a Magento Developer. This is a living document and would love some recommendations on content as well as another set of eyes over the content.

As you might have guessed, this site borrows shamelessly from the brilliant PHP: The Right Way.

Themes

The theme that accompanies your store will invariably be the biggest component of your build and so it’s important to build it correctly.

Blocks

• Develop your blocks in such a way that a future developer can make any modifications required by calling <action method="name" /> in the layout.xml.
• Don’t override the getTemplate() method, or if you do, $this->hasData('template') first.
• Don’t use $this->assign($name, $value) in blocks. Nobody likes surprises.

Back to top

Templates

• Ensure your strings are wrapped with $this->__('') for translations.
• Add /** @var $this Mage_Core_Block_Template */ (replacing the correct class name) at the top of your template file – your IDE will love you.
• Keep as much of your logic in your block as possible. This makes the logic reusable and allows the delegation of templating tasks to less experienced members of staff.

Back to top

Layouts

• Use <update handle="" /> to refactor repeated block declarations.
• Move blocks from one reference to another using <action method="unsetChild"></action> and <action method="insert"></action>.

• Create a local.xml in your theme as a place to store all of your theme modifications. Don’t create catalog.xml, customer.xml, page.xml, etc, files.

• When creating an extension that requires layout changes:
  • Do not ship with your own copy of a local.xml file
  • Create your own layout file with a unique name following your module namespace, for example, $companyname/$modulename.xml
  • Place your layout file (and its accompanying template files) in the base/default theme so that it may be accessed by all installed themes.
• A reusable theme is, for all intents and purposes, an extension to Magento and should also not ship with a customised local.xml (discussion).

Back to top

Extensions

All modifications to the core functionality of Magento should be done by way of Magento extensions.

A strong incentive for migrating to Magento is the number of extensions on Magento Connect. Unlike Apple’s App Store, there is no code review nor quality control procedure to listings. These extensions should reside within the community code pool.

When building a Magento store, it is likely that you will have to add custom code in order to:

• Overwrite core functionality
• Overwrite community extension functionality
• Add independent/additional functionality

These changes should be made in a modular fashion (loosely coupled and high cohesion) within the local code pool.

Do not edit the core code pool.

Third Party Extensions

• Perform a code review of any extension you install on a client site.
• Don’t edit any 3rd party extension directly, because your changes may be lost when the extension is updated. Instead, create your own local module that depends on the one you want to edit and that either rewrites its models/blocks or uses events to achieve the desired effect.
• Check if the extension you are about to install doesn’t rewrite any models or blocks already rewritten by other extensions on your Magento instance. If it does, you are facing a rewrite conflict and you need to make your own local module that depends on both modules (so it’s loaded after them) and rewrites the same models/blocks in a way that won’t prevent any of conflicting modules from working correctly.
• Build a list of trusted (and untrusted) extension providers.

Back to top

Observers

The best way to add code to Magento is to make use of the events system. This allows custom code to be fired upon receipt of an event without having to rewrite models or blocks.

Developing with observers means that the code is more independent and less likely to conflict with other extensions.

• Take a look at this events cheat sheet for an idea of where events are fired.
• When developing your own extensions try and fire events at points where developers may consider extending your code in the future with Mage::dispatchEvent.
• Always try to listen to specific events instead of generic events that are dispatched multiple times during the application life cycle. This will make sure that the code only runs when it’s necessary.

Back to top

Admin Area

• Use an ACL entry to allow administators to restrict, based on user roles, access to your interface.
• Extend from Mage_Adminhtml_Controller_Action when creating your admin controllers to inherit session configuration changes and CSRF mitigation, amongst other things.
• Use the standard /admin prefix for your admin routes instead of inventing your own.

Back to top

Debugging

There are plenty of methods to debug Magento issues. Most problems can be resolved with a fundamental understanding of how components fit together, along with a good idea of where to start looking. For everything else there’s xdebug.

The Varien_Object

• Don’t var_dump(), you’ll probably get a WSOD.

You can inspect the contents of a Varien_Object with the ->debug() method.

Back to top

Logging

• Write to log files in var/log/ by using Mage::log($message, $severity, $filename, $force).
• Use the severity levels as defined in Zend_Log.
• Write to your own file, try to stick to the naming convention $company_$extension_$specific.log, e.g. meanbee_shippingrules_requests.log.
• Add a “Debug Mode” toggle to your extension that forces logging, even if globally disabled.
• eCommerce applications require traceability and the rapid tracking down of issues, so log anything that might make your life easier in the future.
• There’s nothing worse than an empty log file, although a log file full of useless crap comes a close second.

Back to top

Database Queries

• There are a number of methods to retrieve the SQL behind most collection queries for debugging:
  • $collection->getSelect()->assemble()
  • $collection->printLogQuery(true) will echo, $collection->printLogQuery(false, true) will log to system.log
  • Setting the value of Varien_Db_Adapter_Pdo_Mysql::$_debug to true will log all queries to Varien_Db_Adapter_Pdo_Mysql::$_debugFile.

Back to top

Performance

Shops should be fast. Page loading times have a known direct impact on conversion rates.

Frontend

Most of the traditional frontend developer techniques to improve your website’s speed apply to Magento - it’s a web application after all.

• Enable merging CSS and JS files in Magento. You can use Fooman Speedster Advanced for on-the-fly minification and intelligent combined file grouping.

Back to top

Backend

There are few basic methods to speed up Magento installation, a number of which are described in an official Magento whitepaper on the topic.

• For your database server use Percona instead of MySQL.
• For better application performance use PHP version >= 5.4. Here some benchmarks and the latest 5.4 support patch.
• Install a bytecode cache for PHP such as APC.
• Remember to disable Xdebug on production servers.
• Use nginx + php-fpm instead of apache.
• Ensure Magento cache is enabled in production environments.
• Use Varnish for full page caching. Use Turpentine for (almost) drop-in support.
• To reduce SQL queries avoid loading models inside loops, try to get the collection from the database in a single request and iterate over the result set instead.

Back to top

Development Tools

There are a number of tools that have emerged to make your life as a Magento Developer easier.

• modman - Magento Module Manager
• Ecomdev_PHPUnit - PHPUnit Integration
• BehatMage - Behat for Magento
• MageSpec - PHPSpec for Magento
• magerun - Magento Command Line Tools
• magetool - Other magento command line tools.
• dac (Duplicate and Commit) - Easier base/default template duplication for Git
• PHPCS - PHP CodeSniffer. Keep your coding style consistent. Magento specific styles are from Magento ECG and made.com
• PhpStorm with the Magicento plugin - PHPStorm is a full-fledged PHP IDE, and the Magicento plugin adds a lot of Magento-specific features.
• Wiz is a CLI tool for configuring and listing settings from the command line, among other things.

Testing

Testing Magento can be difficult, but there are tools out there to make it easier.

• Ecomdev_PHPUnit - PHPUnit Integration
• BehatMage - Behat for Magento
• MageSpec - PHPSpec for Magento