Magento messages explained

The gaze of red anger when you look at HTML rendered in a core file

For a long period of time, messages.phtml was nothing more than bytes wasted in your Magento installation. Today we will be taking a look at the inner functioning of the messages spawned by Magento.

Magento messages? Huh?

Magento messages are those nifty lines of text you see on the front- and back-end whenever an action, user or system initiated, needs to show bold and clear output. There are a few message states: “error”, “warning”, “notice” and “success”. Because those messages are often temporarily, most developers will know them as “flash messages”. An example of such a message on the front-end:

$this->__('An error occurred while deleting the item from wishlist.')

Message storage

As seen as above, messages get added to an object. Magento core modules might introduce module-specific session namespaces, like that of the customer or catalog. Practically, all messages will be routed through an instance of a subclass of Mage_Core_Model_Session_Abstract which will then internally add them to a Mage_Core_Model_Message_Collection in the super global $_SESSION[$namespace][‘messages’] variable.

On each layout-build, the _prepareLayout method of the Mage_Core_Block_Messages block-class (referenced in page.xml) is responsible for adding all the messages in the “core” session-namespace to the layout its messages block. Back-stepping through the Magento codebase will quickly reveal how tightly coupled the message-block is. By looking at Mage_Core_Block_Abstract there is a getMessagesBlock method which means that everything can have access to the current layout its messages block at all times.

If modules choose to introduce their own session namespace, it becomes their responsibility to add these messages to the global messages block by calling initLayoutMessages with the respective handle of its session storage. For example, the indexAction of the Mage_Customer_AccountController will have two calls for adding the “catalog/session” and “customer/session” storage handles. Having an own session namespace, helps with separating domain logic.

Rendering messages

Though some did have the courage to dive into the core, most developers used to end up puzzled and just leave it with some minor CSS tweaks when looking for a way to customize the Magento messages. Note the emphasis on “used” because in recent Magento versions (>= 1.8) the messages.phtml layout file is actually used on the front-end. Inheriting and customizing it in your template has now become a whole lot easier; you can simply copy the messages.phtml supplied by the default template over to your child theme, add the correct references to your XML file and start customizing.

Due to the nature of Magento its code base, re-factoring is done with little steps at a time. Though the message block its rendering methods might have been replaced by a proper template file in most spots on the front-end, others still use the dreaded getHtml and getGroupedHtml methods for rendering. Sadly, the entire back-end is still suffering from HTML generated in a Magento core class. This StackExchange question has some tips to customize the HTML in those occasions, but if you want more than that you are up for a bumpy ride.


Later this week we will show you how you can utilize events to get some customization for the back-end messages. Heads up, because it will be fragile. 1.8 might have put our hopes up, but we doubt we will see any major improvements regarding the decoupling of the messages block from the core until Magento 2. For that, we will just have to wait a little longer.

Subscribe Newsletter

Subscribe to get latest Magento news

40% Off for 4 Months on Magento Hosting + 30 Free Migration