A very common issue in 2014 was „I updated to Magento 1.8 and now my (login|cart) form is not working anymore”. The reason for this happening was that starting with Magento 1.8, the form key was used in more forms as a security feature (it prevents CSRF attacks). But any theme that had its own version of the according templates did not include the form key, so that the server side validation of the form silently failed.

Of course there are themes whose markups are so different from the default theme, that most templates are overridden with good reason. However I see at least as many themes, especially custom themes, where all templates were copied from base/default and then modified. There is almost no excuse to overwrite layout XML files because one can modify the layout in many ways with an additional theme specific local.xml file.

The issue mentioned above is a good example of the reasons for the „pay attention to updatability“ mantra. The errors could have been avoided if only files had been copied, that really required adjustment(s).

With this article I want to explain the process I’m following for theme refactoring (just the structural part, the HTML source will look exactly as before afterwards — except from changes in newer versions of the default templates). Kalen Jordan’s magerun-addons with their diff:theme command were really helpful for that — I added a few features to aid my process, which are now merged into the addons, so with the latest version you can use them right away:

• The --raw parameter gives out only the file names instead of a human readable table, allowing the output to be piped into other commands
• The --filter parameter allows filtering the results. At the moment there are two filters: only-equal and only-different
• The --ignore-copyright parameter excludes the „license“ and „copyright“ lines from the diff, so that identical files from different Magento versions are still counted as identical

To use the tool, you need the Magento command line utility n98-magerun and to install the magerun-addons as plugin (there are several ways to do so). The linked resources contain enough documentation, so I’ll spare you the details and dive directly into the refactoring:

Step 1. Remove exact copies

This can be done with the theme comparison command of the magerun-addons. However the theme is often a copy of base/default or default/modern from an older Magento version. This is why we need the original files for the comparison.

How to find out on which version the theme was based? Have a look at the copyright notice in the header of the template files. The following table shows which versions of Magento CE have which copyright notice. To distinguish Magento 1.4 from Magento 1.5 you will need to look at the actual diffs:

Version	@copyright
Magento 1.9	Copyright (c) 2006-2014 X.commerce, Inc. (http://www.magento.com)
Magento 1.8	Copyright (c) 2013 Magento Inc. (http://www.magentocommerce.com)
Magento 1.7	Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
Magento 1.6	Copyright (c) 2011 Magento Inc. (http://www.magentocommerce.com)
Magento 1.4.1-1.5	Copyright (c) 2010 Magento Inc. (http://www.magentocommerce.com)
Magento 1.4.0	Copyright (c) 2009 Irubin Consulting Inc. DBA Varien (http://www.varien.com)
Magento 1.0-1.3	Copyright (c) 2008 Irubin Consulting Inc. DBA Varien (http://www.varien.com)

Let’s say, our theme „legacy/default“ is based on the modern theme of Magento 1.5, then we download Magento 1.5 and copy the theme files as follows:

• magento15/default ←base/default
• magento15/modern ← default/modern

and then run the following command

voilà, duplicates have been removed.

Step 2. Move identical modifications to a default theme

If you have a store with several similar themes, identical modifications should be moved to a „default“ theme. So if our „legacy“ package has two themes „crap“ and „crapper“, you should search again for identical files, but this time without deleting them right away:

This gives us a list of identical files to move to „legacy/default“.

Step 3. Diff all the XML

Now comes the first part that requires actual thinking and Magento knowledge. We look at the changes that have been made to the layout XML files and try to convert them all to adjustments in local.xml. The following command shows the diff:

At the end, the ideal case is if you dont have any files in legacy/default/layout but in the local.xml. If you have a Magento Version CE 1.9/EE 1.14 or newer, don’t use local.xml at all and use legacy/default/etc/theme.xml instead, see this blog.

Result

And this is how the commit of a successfully refactored theme structure can look like:

Which is good, considering that the best code is no code at all.