# FlashMessenger

## Introduction

The FlashMessenger helper allows you to pass messages that the user may need to see on the next request. To accomplish this, FlashMessenger uses `Zend_Session_Namespace` to store messages for future or next request retrieval. It is generally a good idea that if you plan on using `Zend_Session` or `Zend_Session_Namespace`, that you initialize with `Zend_Session::start()` in your bootstrap file. (See the Zend_Session documentation for more details on its usage.)

## Available Methods

General methods:

- `setNamespace($namespace='default')` is used to set the namespace into which messages are stored by default.

- `getNamespace()` is used to retrieve the name of the default namespace. The default namespace is 'default'.

- `resetNamespace()` is used to reset the namespace name to the default value, 'default'.

Methods for manipulating messages set in the previous request:

- `hasMessages($namespace=NULL)` is used to determine if messages have been carried from a previous request by the flash messenger. The optional argument `$namespace` specifies which namespace to look in. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `getMessages($namespace=NULL)` is used to retrieve the messages which have been carried from a previous request by the flash messenger. The optional argument `$namespace` specifies which namespace to pull from. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `getIterator($namespace=NULL)` wraps the return value of `getMessages()` in an instance of `ArrayObject`. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `count($namespace=NULL)` returns the number of messages contained in the specified namespace. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `clearMessages($namespace=NULL)` is used to clear all the messages which have been carried from a previous request by the flash messenger. The optional argument `$namespace` specifies which namespace to clear out. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

Methods for manipulating messages set in the current request:

- `addMessage($message, $namespace=NULL)` is used to add a new message to the current request. `$message` contains the message to be added, and the optional argument `$namespace` will specify the namespace. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `hasCurrentMessages($namespace=NULL)` is used to determine if messages have been added to the flash messenger during the current request. The optional argument `$namespace` specifies which namespace to look in. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `getCurrentMessages($namespace=NULL)` is used to retrieve the messages which have been added to the flash messenger during the current request. The optional argument `$namespace` specifies which namespace to pull from. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

- `clearCurrentMessages($namespace=NULL)` is used to clear all the messages which have been added to the flash messenger during the current request. The optional argument `$namespace` specifies which namespace to clear out. If the `$namespace` argument is omitted, the value returned by `getNamespace()` will be used.

## Basic Usage Example

The usage example below shows the use of the flash messenger at its most basic. When the action `/some/my` is called, it adds the flash message "Record Saved!" A subsequent request to the action `/some/my-next-request` will retrieve it (and thus delete it as well).

    class SomeController extends Zend_Controller_Action
    {
        /**
         * FlashMessenger
         *
         * @var Zend_Controller_Action_Helper_FlashMessenger
         */
        protected $_flashMessenger = null;

        public function init()
        {
            $this->_flashMessenger =
                $this->_helper->getHelper('FlashMessenger');
            $this->initView();
        }

        public function myAction()
        {
            /**
             * default method of getting
             * Zend_Controller_Action_Helper_FlashMessenger instance
             * on-demand
             */
            $this->_flashMessenger->addMessage('Record Saved!');
        }

        public function myNextRequestAction()
        {
            $this->view->messages = $this->_flashMessenger->getMessages();
            $this->render();
        }
    }