Yireo Guidelines for Magento Modification

In the past, Yireo has seen so many Magento sites that were build using wrong procedures, resulting in corrupt Magento applications that could not be upgraded. The key here is that the customer (you) doesn't ask for quality with the right terminology, and the developer doesn't read the manual. Here are own guidelines, that hopefully can serve you to control your Magento modifications.

Create a backup before hiring

Make a complete site-backup of both all the Magento files as well as the Magento database, before you hire a developer. When things go bad (or a developer goes rogue), you at least have a full backup of the previous situation. Restoring from that backup might be unwise in some cases - for instance, when the database-structure changed dramatically. But at least you can use a UNIX-tool like diff to trace down all modifications.

Control access to your Magento site

When allowing a developer access to your environment, SSH is preferred. But if you don't trust the developer fully, do not hand-over the main SSH-account - instead opt for a FTP-account that is limiting the developer to a certain folder. If you do hand-over important accounts like the SSH-account, consider changing the passwords afterwards.

Ofcourse, no changes should ever be made to a production environment directly, so setup a testing environment. If you don't know how to setup a testing environment, do not save money by directlying modifying the production site - but instead, hire a developer to setup this testing environment for you.

No core hacks

Magento is flexible and powerful. Thanks to its architecture, anything (whether it be a PHP-class, a template-file, a language-string, or an image) can be overridden in a way, that does not touch the original file. That way, you can keep upgrading Magento to newer versions, without the danger of loosing your modifications. Core hacks are never needed in Magento.

Any developer that makes a core hack in Magento should be fired on the spot. Not only because it is wrong to make core hacks in Magento, but also because the first chapters of most Magento books start of by telling that core hacks are never needed in Magento.

To summarize the overrides possible in Magento:

  • When making theming changes, a custom Magento theme can be configured in the Magento System Configuration. If only a few files need to be modified, this new theme can be extending a parent theme (default theme). To override a PHTML-file for instance, the file simply needs to be copied to the child-theme folder.
  • When making changes to the XML-layout (part of the Magento theme), XML-files can be copied to the layout-folder of the custom theme. But instead, the XML-commands can also be saved in an additional file layout/etc/local.xml instead. This makes it directly visible what changes you made to your site.
  • Language-files in app/locale should never be touched. Instead, a Magento theme can override any language-file. When changes are limited, an additional file translate.csv can be used to contain only the modifications made.
  • Magento logic can be extended by programming custom Observers that listen to specific events. This is the best way for modifying the underlying system logic.
  • If this fails, a custom extension can remap a class by using XML-rewrites in its own etc/config.xml file. This method is very powerful, but extensions can conflict if they try to rewrite the same class. This should not be used frequently.
  • Finally, PHP-classes can be overridden by copying their files to another code-pool (from core to community, from community to local, from core to local). However, this should be used only as a final resort. A Magento site where there are more than 10 files copied this way, definitely lacks a proper architecture.

Magento extensions should be in app/code/community

Magento has created three code-pools for Magento extensions to be placed in: The folder core is restricted to the Magento core only; the folder community is ment for third party Magento extensions; the folder local is ment for local changes. Some extension-developers seem to think that their extension should be placed in the local pool, because their extension is not available on the MagentoConnect marketplace - this is incorrect: The community pool is ment for any third party extension that is used on multiple sites, so therefor it doesn't classify as a local modification.

Why care? In the listing above, you could have read that files can be overridden by moving them from one pool to another: Files in the core-pool can be overridden by copying them to the local-pool. But files in the local-pool can not be copied anywhere. Therefor modifying files in the local-pool that actually belong to a third party extension, is actually considered a core hack. To allow overriding of files, any third party extension that is not written for local usage only, should be placed in the community-pool.

Reporting is clue

When making changes anywhere in the Magento system, it is vital to document it. Magento already is a complex application, and it is not uncommon that a developer spends 95% of his time to track down the problem, while 5% of the time is spent on actually solving the problem. Having proper documentation in place might save you time and money.

  • Document the Magento core-version and the main features that are needed by your shop. If a new Magento version comes out, you can summarize why an upgrade would be needed.
  • Document the Magento extensions that are used. It's also best to classify which extensions are used for what purpose. If an extension is vital for your business logic, it should be marked as more important than an extension that only adds a fancy JavaScript-effect.
  • When changes are made, write down what these changes actually were - maintain a changelog: Which files were modified for what purpose. It would be even better if the line-numbers of the modified code were also written down. Inline code-commenting is another way to deal with this. Yet another way is to use some kind of versioning system like Subversion or Git - but this is probably only for more advanced developers.