ZF-8494 - Add and document method that returns only the valid values of the submitted data to a form.

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

documentation/manual/en/module_specs/Zend_Form-Forms.xml

@@ -1528,6 +1528,25 @@ $messages = $form->getMessages('username');
                 All errors set in this fashion may be translated.
             </para>
         </sect3>
+
+        <sect3 id="zend.form.forms.validation.values">
+            <title>Retrieving Valid Values Only</title>
+
+            <para>
+                There are scenarios when you want to allow your user to work on a valid form
+                in several steps. Meanwhile you allow the user to save the form with any
+                set of values inbetween. Then if all the data is specified you can transfer
+                the model from the building or prototying stage to a valid stage.
+            </para>
+
+            <para>
+                You can retrieve all the valid values that match the submitted data by calling:
+            </para>
+
+            <programlisting language="php"><![CDATA[
+$validValues = $form->getValidValues($_POST);
+]]></programlisting>
+        </sect3>
     </sect2>
 
     <sect2 id="zend.form.forms.methods">

documentation/manual/en/module_specs/Zend_Form-QuickStart.xml

@@ -415,6 +415,15 @@ $values = $form->getValues();
         <programlisting language="php"><![CDATA[
 $unfiltered = $form->getUnfilteredValues();
 ]]></programlisting>
+
+        <para>
+            If you on the other hand need all the valid and filtered values of a partially valid form,
+            you can call:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$values = $form->getValidValues($_POST);
+]]></programlisting>
     </sect2>
 
     <sect2 id="zend.form.quickstart.errorstatus">

library/Zend/Form.php

@@ -1316,6 +1316,35 @@ class Zend_Form implements Iterator, Countable, Zend_Validate_Interface
     }
 
     /**
+     * Returns only the valid values from the given form input.
+     *
+     * For models that can be saved in a partially valid state, for example when following the builder,
+     * prototype or state patterns it is particularly interessting to retrieve all the current valid
+     * values to persist them.
+     *
+     * @param  array $data
+     * @return array
+     */
+    public function getValidValues($data)
+    {
+        $values = array();
+        foreach ($this->getElements() as $key => $element) {
+            if (isset($data[$key])) {
+                if($element->isValid($data[$key], $data)) {
+                    $values[$key] = $element->getValue();
+                }
+            }
+        }
+        foreach ($this->getSubForms() as $key => $form) {
+            if (isset($data[$key])) {
+                $values[$key] = $form->getValidValues($data[$key]);
+            }
+        }
+
+        return $values;
+    }
+
+    /**
      * Get unfiltered element value
      *
      * @param  string $name

tests/Zend/Form/FormTest.php

@@ -53,6 +53,11 @@ require_once 'Zend/View.php';
  */
 class Zend_Form_FormTest extends PHPUnit_Framework_TestCase
 {
+    /**
+     * @var Zend_Form
+     */
+    public $form;
+
     public static function main()
     {
         $suite  = new PHPUnit_Framework_TestSuite('Zend_Form_FormTest');
@@ -3751,6 +3756,49 @@ class Zend_Form_FormTest extends PHPUnit_Framework_TestCase
     }
 
     /**
+     * @group ZF-8494
+     */
+    public function testGetValidValues()
+    {
+        $data = array('valid' => 1234, 'invalid' => 'invalid', 'noElement' => 'noElement');
+
+        require_once "Zend/Validate/Int.php";
+
+        $validElement = new Zend_Form_Element("valid");
+        $validElement->addValidator(new Zend_Validate_Int());
+        $this->form->addElement($validElement);
+
+        $invalidElement = new Zend_Form_Element('invalid');
+        $invalidElement->addValidator(new Zend_Validate_Int());
+        $this->form->addElement($invalidElement);
+
+        $this->assertEquals(array('valid' => 1234), $this->form->getValidValues($data));
+    }
+
+    /**
+     * @group ZF-8494
+     */
+    public function testGetValidSubFormValues()
+    {
+        $data = array('sub' => array('valid' => 1234, 'invalid' => 'invalid', 'noElement' => 'noElement'));
+
+        require_once "Zend/Validate/Int.php";
+
+        $subForm = new Zend_Form_SubForm();
+        $validElement = new Zend_Form_Element("valid");
+        $validElement->addValidator(new Zend_Validate_Int());
+        $subForm->addElement($validElement);
+
+        $invalidElement = new Zend_Form_Element('invalid');
+        $invalidElement->addValidator(new Zend_Validate_Int());
+        $subForm->addElement($invalidElement);
+
+        $this->form->addSubForm($subForm, 'sub');
+
+        $this->assertEquals(array('sub' => array('valid' => 1234)), $this->form->getValidValues($data));
+    }
+
+    /**
      * Used by test methods susceptible to ZF-2794, marks a test as incomplete
      *
      * @link   http://framework.zend.com/issues/browse/ZF-2794