ZF-1705: Added optional namespace argument to message methods in FlashMessenger controller action helper

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@24784 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Controller-ActionHelpers-FlashMessenger.xml

@@ -20,6 +20,128 @@
         </para>
     </sect4>
 
+    <sect4 id="zend.controller.actionhelper.flashmessenger.api">
+        <title>Available Methods</title>
+
+        <para>
+            General methods:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <methodname>setNamespace($namespace='default')</methodname> is used to set the namespace
+                     into which messages are stored by default. 
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>getNamespace()</methodname> is used to retrieve the name of the 
+                    default namespace.  The default namespace is 'default'.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>resetNamespace()</methodname> is used to reset the namespace name
+                    to the default value, 'default'.
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            Methods for manipulating messages set in the previous request:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <methodname>hasMessages($namespace=NULL)</methodname> is used to determine
+                    if messages have been carried from a previous request by the flash messenger.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to look in.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>getMessages($namespace=NULL)</methodname> is used to retrieve the
+                    messages which have been carried from a previous request by the flash messenger.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to pull from.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>getIterator($namespace=NULL)</methodname> wraps the return value of 
+                    <methodname>getMessages()</methodname> in an instance of <classname>ArrayObject</classname>.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>count($namespace=NULL)</methodname> returns the number of messages contained
+                    in the specified namespace.  If the <varname>$namespace</varname> argument is omitted, the 
+                    value returned by <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>clearMessages($namespace=NULL)</methodname> is used to clear all the
+                    messages which have been carried from a previous request by the flash messenger.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to clear out.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            Methods for manipulating messages set in the current request:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <methodname>addMessage($message, $namespace=NULL)</methodname> is used to add a new 
+                    message to the current request.  <varname>$message</varname> contains the message
+                    to be added, and the optional argument <varname>$namespace</varname> will specify
+                    the namespace.  If the <varname>$namespace</varname> argument is omitted, the value
+                    returned by <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>hasCurrentMessages($namespace=NULL)</methodname> is used to determine
+                    if messages have been added to the flash messenger during the current request.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to look in.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>getCurrentMessages($namespace=NULL)</methodname> is used to retrieve the
+                    messages which have been added to the flash messenger during the current request.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to pull from.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    <methodname>clearCurrentMessages($namespace=NULL)</methodname> is used to clear all the
+                    messages which have been added to the flash messenger during the current request.  The
+                    optional argument <varname>$namespace</varname> specifies which namespace to clear out.
+                    If the <varname>$namespace</varname> argument is omitted, the value returned by
+                    <methodname>getNamespace()</methodname> will be used.
+                </para>
+            </listitem>
+        </itemizedlist>
+
+    </sect4>
+
     <sect4 id="zend.controller.actionhelper.flashmessenger.basicusage">
         <title>Basic Usage Example</title>
 

library/Zend/Controller/Action/Helper/FlashMessenger.php

@@ -112,6 +112,16 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
         $this->_namespace = $namespace;
         return $this;
     }
+    
+    /**
+     * getNamespace() - return the current namepsace
+     * 
+     * @return string
+     */
+    public function getNamespace()
+    {
+        return $this->_namespace;
+    }
 
     /**
      * resetNamespace() - reset the namespace to the default
@@ -130,17 +140,21 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      * @param  string $message
      * @return Zend_Controller_Action_Helper_FlashMessenger Provides a fluent interface
      */
-    public function addMessage($message)
+    public function addMessage($message, $namespace = null)
     {
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
         if (self::$_messageAdded === false) {
             self::$_session->setExpirationHops(1, null, true);
         }
 
         if (!is_array(self::$_session->{$this->_namespace})) {
-            self::$_session->{$this->_namespace} = array();
+            self::$_session->{$namespace} = array();
         }
 
-        self::$_session->{$this->_namespace}[] = $message;
+        self::$_session->{$namespace}[] = $message;
 
         return $this;
     }
@@ -150,9 +164,13 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return boolean
      */
-    public function hasMessages()
+    public function hasMessages($namespace = null)
     {
-        return isset(self::$_messages[$this->_namespace]);
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        return isset(self::$_messages[$namespace]);
     }
 
     /**
@@ -160,10 +178,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return array
      */
-    public function getMessages()
+    public function getMessages($namespace = null)
     {
-        if ($this->hasMessages()) {
-            return self::$_messages[$this->_namespace];
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        if ($this->hasMessages($namespace)) {
+            return self::$_messages[$namespace];
         }
 
         return array();
@@ -174,10 +196,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return boolean True if messages were cleared, false if none existed
      */
-    public function clearMessages()
+    public function clearMessages($namespace = null)
     {
-        if ($this->hasMessages()) {
-            unset(self::$_messages[$this->_namespace]);
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        if ($this->hasMessages($namespace)) {
+            unset(self::$_messages[$namespace]);
             return true;
         }
 
@@ -190,9 +216,13 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return boolean
      */
-    public function hasCurrentMessages()
+    public function hasCurrentMessages($namespace = null)
     {
-        return isset(self::$_session->{$this->_namespace});
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        return isset(self::$_session->{$namespace});
     }
 
     /**
@@ -201,10 +231,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return array
      */
-    public function getCurrentMessages()
+    public function getCurrentMessages($namespace = null)
     {
-        if ($this->hasCurrentMessages()) {
-            return self::$_session->{$this->_namespace};
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        if ($this->hasCurrentMessages($namespace)) {
+            return self::$_session->{$namespace};
         }
 
         return array();
@@ -215,10 +249,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return boolean
      */
-    public function clearCurrentMessages()
+    public function clearCurrentMessages($namespace = null)
     {
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
         if ($this->hasCurrentMessages()) {
-            unset(self::$_session->{$this->_namespace});
+            unset(self::$_session->{$namespace});
             return true;
         }
 
@@ -230,10 +268,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return ArrayObject
      */
-    public function getIterator()
+    public function getIterator($namespace = null)
     {
-        if ($this->hasMessages()) {
-            return new ArrayObject($this->getMessages());
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        if ($this->hasMessages($namespace)) {
+            return new ArrayObject($this->getMessages($namespace));
         }
 
         return new ArrayObject();
@@ -244,10 +286,14 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      *
      * @return int
      */
-    public function count()
+    public function count($namespace = null)
     {
-        if ($this->hasMessages()) {
-            return count($this->getMessages());
+        if (!is_string($namespace) || $namespace == '') {
+            $namespace = $this->getNamespace();
+        }
+        
+        if ($this->hasMessages($namespace)) {
+            return count($this->getMessages($namespace));
         }
 
         return 0;
@@ -259,8 +305,8 @@ class Zend_Controller_Action_Helper_FlashMessenger extends Zend_Controller_Actio
      * @param  string $message
      * @return void
      */
-    public function direct($message)
+    public function direct($message, $namespace=NULL)
     {
-        return $this->addMessage($message);
+        return $this->addMessage($message, $namespace);
     }
 }

tests/Zend/Controller/Action/Helper/FlashMessengerTest.php

@@ -30,6 +30,7 @@ require_once 'Zend/Controller/Request/Http.php';
 require_once 'Zend/Controller/Response/Cli.php';
 require_once 'Zend/Controller/Action/HelperBroker.php';
 require_once 'Zend/Controller/Action/Helper/FlashMessenger.php';
+require_once 'Zend/Controller/Exception.php';
 require_once 'Zend/Session.php';
 require_once dirname(dirname(dirname(__FILE__))) . '/_files/HelperFlashMessengerController.php';
 
@@ -106,7 +107,7 @@ class Zend_Controller_Action_Helper_FlashMessengerTest extends PHPUnit_Framework
         $this->request->setControllerName('helper-flash-messenger');
         $this->response   = new Zend_Controller_Response_Cli();
         $this->controller = new HelperFlashMessengerController($this->request, $this->response, array());
-        $this->helper     = new Zend_Controller_Action_Helper_FlashMessenger($this->controller);
+        $this->helper     = new Zend_Controller_Action_Helper_FlashMessenger;
     }
 
     public function testLoadFlashMessenger()
@@ -136,6 +137,99 @@ class Zend_Controller_Action_Helper_FlashMessengerTest extends PHPUnit_Framework
         $this->assertTrue($this->helper->hasMessages());
         $this->assertEquals(1, count($this->helper));
     }
+
+    /**
+     * @group ZF-1705
+     */
+    public function testNamespaceChange()
+    {
+        $this->helper->setNamespace('foobar');
+        $this->assertEquals('foobar', $this->helper->getNamespace());
+    }
+
+    /**
+     * @group ZF-1705
+     */
+    public function testAddMessageToCustomNamespace()
+    {
+        $this->helper->addMessage('testmessage', 'foobar');
+        $this->assertTrue($this->helper->hasCurrentMessages('foobar'));
+        $foobarMessages = $this->helper->getCurrentMessages('foobar');
+        $this->assertEquals(1, count($foobarMessages));
+        $this->assertEquals('testmessage', array_pop($foobarMessages));
+
+        // Ensure it didnt' bleed over into default namespace
+        $defaultMessages = $this->helper->getCurrentMessages();
+        $this->assertTrue(empty($defaultMessages), 'Default namespace not empty');
+    }
+
+    /**
+     * @group ZF-1705
+     */
+    public function testRemoveMessageToCustomNamespace()
+    {
+        // Place a message in foobar and default namespaces
+        $this->helper->addMessage('testmessage', 'foobar');
+        $this->assertTrue($this->helper->hasCurrentMessages('foobar'));
+        $this->helper->addMessage('defaultmessage');
+        $this->assertTrue($this->helper->hasCurrentMessages());
+
+        // Erase the foobar namespace
+        $this->helper->clearCurrentMessages('foobar');
+
+        // Ensure it cleared the specified namespace
+        $foobarMessages = $this->helper->getCurrentMessages('foobar');
+        $this->assertTrue(empty($foobarMessages), 'Namespace foobar not empty');
+
+        // Ensure it didnt' clear the default namespace
+        $defaultMessages = $this->helper->getCurrentMessages();
+        $this->assertEquals(1, count($defaultMessages));
+        $this->assertEquals('defaultmessage', array_pop($defaultMessages));
+    }
+
+    /**
+     * @group ZF-1705
+     */
+    public function testSimulateCrossRequestMessagePassing()
+    {
+        $helper = new FlashMessengerControllerActionHelper;
+        $helper->addMessage('testmessage', 'foobar');
+        $helper->addMessage('defaultmessage');
+
+        // Reset and recreate the helper, essentially faking a subsequent request
+        $helper->reset();
+        $helper = new FlashMessengerControllerActionHelper;
+
+        // Check the contents
+        $this->assertFalse($helper->hasCurrentMessages('foobar'));
+        $this->assertFalse($helper->hasCurrentMessages());
+        $this->assertTrue($helper->hasMessages('foobar'));
+        $this->assertTrue($helper->hasMessages());
+
+        $defaultMessages = $helper->getMessages();
+        $this->assertEquals(1, count($defaultMessages));
+        $this->assertEquals('defaultmessage', array_pop($defaultMessages));
+
+        $foobarMessages = $helper->getMessages('foobar');
+        $this->assertEquals(1, count($foobarMessages));
+        $this->assertEquals('testmessage', array_pop($foobarMessages));
+    }
+}
+
+/**
+ * Subclass of FlashMessenger action helper which exposes a reset method
+ * to allow faking a second (fresh) request
+ */
+class FlashMessengerControllerActionHelper extends Zend_Controller_Action_Helper_FlashMessenger
+{
+    public function getName() { return 'FlashMessenger'; }
+
+    public function reset()
+    {
+        self::$_messages = array();
+        self::$_session = NULL;
+        self::$_messageAdded = false;
+    }
 }
 
 // Call Zend_Controller_Action_Helper_FlashMessengerTest::main() if this source file is executed directly.