Using The Zend Framework FlashMessenger

The FlashMessenger in Zend Framework has a bit of an odd name as it has nothing to do with Adobe Flash at all. It is a controller action helper defined in the class Zend_Controller_Action_Helper_FlashMessenger, which is used to store and retrive messages that are temporarily stored in the user's session. This is useful if you want to provide form validation and redirection at the same time as you can print out messages after the page has been loaded. If you are familiar with Drupal then this class acts in the same kind of way as the drupal_set_messages() function.

Because FlashMessenger is an action helper it can be initialized in a number of different ways, however, using the _helper property (the helper broker) of the controller is probably the easiest way. The FlashMessenger can be retrived through the helper broker in the following ways:

By using getHelper() method of the helper broker, passing the name of the helper that we want to return.

$flashMessenger = $this->_helper->getHelper('FlashMessenger');

We can also use the __get() magic method of the helper broker to return the FlashMessenger helper as if it was a property of the helper broker object.

$flashMessenger = $this->_helper->FlashMessenger;

Using the FlashMessenger action helper is very easy. To add a message to the FlashMessenger we would use the addMessage() method and to get any messages that have been set use the getMessages() method. You can test this out by adding the following code into one of your controller methods. It will pass any messages set to the view and then send the string 'Hello, World' to the FlashMessenger helper.

$flashMessenger = $this->_helper->getHelper('FlashMessenger');
$this->view->myMessages = $flashMessenger->getMessages();
$flashMessenger->addMessage('Hello, World');

On the first request the getMessages() method will return an empty array and an array containing the set messages on the second request. Put the following into your view and you will see the string "Hello World" being printed after the first page refresh.

print_r($this->myMessages);

I should note here that the addMessage() of the FlashMessenger action helper can be called directly by passing a string to the helper broker. This happens because the FlashMessenger action helper implements the direct() method, which will call a default method in the helper. Most action helpers have this sort of functionality.

$this->_helper->FlashMessenger('We did something in the last request');

You can also segregate any messages you have into different sections by using the setNamespace() method. This takes a string as a single parameter and will group all messages set onto this string. The FlashMessenger uses a default namespace, called 'default'. The following code sets up a namespace called "myMessages" and adds a message to it.

$flashMessenger = $this->_helper->getHelper('FlashMessenger');
$flashMessenger->setNamespace('myMessages');
$this->view->myMessages = $flashMessenger->getMessages();
$flashMessenger->addMessage('Hello, World');

You can change the namespace at any time, or even reset the namespace back to default by using the resetNamespace() method. This allows you to, for example, only add form validation messages to a form namespace and system messages to a system namespace.

A tidy way of using the FlashMessenger is to encapsulate it into a helper method within the action controller. This saves having to get the FlashMessenger object and setting a namespace every time you want to use it. The following method can be added to a controller class and will store a single message that is passed to it.

protected function _flashMessage($message) {
    $flashMessenger = $this->_helper->FlashMessenger;
    $flashMessenger->setNamespace('myMessages');
    $flashMessenger->addMessage($message);
}

The following code shows two different calls to this method, each setting a different value.

$this->_flashMessage('Message!');    
$this->_flashMessage('Random number = ' . rand());

The messages are then sent to the view using the following code, this can also be encapsulated into its own method if you want.

$flashMessenger = $this->_helper->FlashMessenger;
$flashMessenger->setNamespace('myMessages');
$this->view->myMessages = $flashMessenger->getMessages();

If you want to first check to see if there are any messages available you can use the hasMessaged() method. This will return true if the message namespace you have selected contains any messages.

$flashMessenger->hasMessages();

Within the view script file the following code snippet can be used to print out the messages in a block. Using a loop means that you can add multiple messages and still expect the output to look nice.

<?php
if (isset($this->myMessages)) {
    $result = '';
    $result .= '<ul>' . PHP_EOL;
    foreach ($this->myMessages as $message) {
        $result .= '<li>' . $message . '</li>' . PHP_EOL;
    }
    $result .= '</ul>' . PHP_EOL;
    echo $result;
}
?>

To clear all of the messages from a namespace you can use the clearMessages() function. There is also a count() method that will return the number of messages available.

So far I have only looked at the normal message manipulation methods. The addMessage() method will always add a message to the current namespace, but when inspecting messages you can use a number of methods that will only look at those messages set within the current request. The hasCurrentMessages() method is used to find out if any messages have been added to the current request. The getCurrentMessages() returns any messages that have been added to the current request. The following shows these methods in action.

$flashMessenger = $this->_helper->FlashMessenger;
$flashMessenger->setNamespace('myMessages');

print_r($flashMessenger->getMessages());

$flashMessenger->addMessage('Hello World');

$flashMessenger->hasCurrentMessages();
print_r($flashMessenger->getCurrentMessages());

The code above will print out a single 'Hello World' after loading the page the first time from the getCurrentMessages() method call. It will then print two 'Hello World' strings after reloading the page due to the getMessages() method call.