Magento tutorial: how to overload a Varien class?

If you have read my previous post about Magento overloading mechanism, you’ll see that there is two existing mechanisms to overload classes in Magento

But these two mechanisms are only available for classes which are instantiated.

Many of Varien classes are not loaded directly through a new. So how we can overload them?

If class is only used when using extends, we have only one way to overload it’s content: the passive overload

This mechanism is based upon the auto-loading mechanism embedded with Magento

  • Loading first from app/code/local folder
  • Then first look for classes in app/code/community
  • If always not found, look for the app/code/core folder
  • Always not found? look for lib folder

The only way you can use to overload a Varien class is to use this mechanism to provide your own functionalities by copying Varien class in app/code/community or app/code/local folder (we do not touch at the app/code/core)

By using this method, this is your class which will be loaded, instead of Varien one

Magento Overloading mecanisms

Magento is a really rich software application. However, its management rules may be diffrent from your own management.
Varien, Magento’s editor, forecasted this case and offers 2 overloading methods of its native working to allow you to adapt the solution to your specificities.

One of these mechanism is a passive overloading, whether the other needs your intervention.

Passive overloading

This overloading mechanism is closely related to Magentos’s autoload management.

Source code organization in Magento & Autoload

Reminder of source code organization in Magento

For recall, autoload is a mechanism born with PHP5 which embeds a dynamic class loader manager.
That is to say, if a class was never loaded, it’s the __autoload method which will search and find in which source if the required class exists. This method may be redefined to adapt your needs.

Magento’s source code is organized according to four repositories

  • Libraries. That’s where you will find, in particular, the Zend Framework which is a referencial for librairies in Magento
  • Magento’s core. It’s in the folder app/code/core
  • Community enrichment. They’re in the folder app/code/community
  • Local enrichment. They’re in the folder app/code/local


So these four folders are : lib, app/code/core, app/code/community, app/code/local

Magento defines its own autoloader in the Autoload class, located in the folder lib/Varien.

This autoloader will first look for classes in app/code/local, and then if it doesn’t find them, in app/code/community, and lastly in app/code/core if it still hasn’t found the right file. After all, if the file is still not found, it will be searched in the libs.

Working of passive overloading in Magento

Everything bases on this autoloader’s working : it’s therefore possible, by acting on the autoload priorities, to make a preferential choice about a local adaptation (which would be in app/code/local), rather than the native file which is in app/code/core.

This requires however that the local adaptation contains fully all the methods that are in the overloaded class.

An example of this kind of overloading is the file app/code/core/Zend/Mime.php which is used instead of the file lib/Zend/Mime.php.

Active overloading

This overloading mechanism is related to instanciation mechanism used in Magento.

Instanciation mechanism in Magento

For recall, Magento uses three generic methods to load its classes :

Mage::getModel() (and Mage::getSingleton)
Mage::getBlockSingleton
Mage::helper()

These methods will be in charge of determining the name of the class to be loaded.

What happens in case of two active overloading of the same class ?

Magento’s rules manager is confused and doesn’t know which class it has to load anymore. In this case you will surely note stange behaviours.

It’s then higly recommanded that you never fall in this case, and be therefore most carefull when you install modules from the community which might already overload the same objects as you.

Which overloading mechanism choose ?

It depends on what you wish to implement, and also on the type of class you wish to overload. Abstract classes for example cannot be overloaded with the active overloading mechanism, because they don’t have a real instanciation. To overload them, you have to choose passive overloading. With active overloading you don’t have to rewrite the full content of the overloaded class, unlike in the passive overloading case.
You also will have less compelling maintenance of your source code referring to this overloading concerning Magento upgrades.

This loading mechanism break also a common bias we can heard: “community folder is only for sources code coming from magento connect”. In this case, if we put our own development only in local folder, we avoid usage of passive overload. is it really the thing you wants?