[ZF-8156] Zend_Validate_Identical:

- allow manual configuration usage
- added new section for this validator

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

documentation/manual/en/module_specs/Zend_Validate-Identical.xml

@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.validate.set.identical">
+
+    <title>Identical</title>
+
+    <para>
+        <classname>Zend_Validate_Identical</classname> allows you to validate if a given value is
+        identical with an set haystack.
+    </para>
+
+    <sect3 id="zend.validate.set.identical.basic">
+        <title>Basic usage</title>
+
+        <para>
+            To validate if two values are identical you need to set the origin value as haystack.
+            See the following example which validates two strings.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$valid = new Zend_Validate_Identical('origin');
+if ($valid->isValid($value) {
+    return true;
+}
+]]></programlisting>
+
+        <para>
+            The validation will only then return <constant>TRUE</constant> when both values are
+            100% identical. In our example, when <varname>$value</varname> is 'origin'.
+        </para>
+
+        <para>
+            You can set the wished token also afterwards by using the method
+            <methodname>setToken()</methodname> and <methodname>getToken()</methodname> to get
+            the actual set token.
+        </para>
+    </sect3>
+
+    <sect3 id="zend.validate.set.identical.types">
+        <title>Identical objects</title>
+
+        <para>
+            Of course <classname>Zend_Validate_Identical</classname> can not only validate strings,
+            but also any other variable type like Boolean, Integer, Float, Array or even Objects.
+            As already noted Haystack and Value must be identical.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$valid = new Zend_Validate_Identical(123);
+if ($valid->isValid($input)) {
+    // input appears to be valid
+} else {
+    // input is invalid
+}
+]]></programlisting>
+
+        <note>
+            <title>Type comparison</title>
+
+            <para>
+                You should be aware that also the type of a variable is used for validation.
+                This means that the string <emphasis>'3'</emphasis> is not identical with the
+                integer <emphasis>3</emphasis>.
+            </para>
+
+            <para>
+                This is also the case for Form Elements. They are objects or arrays. So you can't
+                simply compare a Textfield which contains a password with an textual password
+                from another source. The Element itself is given as array which also contains
+                additional informations.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.validate.set.identical.types">
+        <title>Configuration</title>
+
+        <para>
+            As all other validators also <classname>Zend_Validate_Identical</classname> supports
+            the usage of configuration settings as input parameter. This means that you can
+            configure this validator with an <classname>Zend_Config</classname> object.
+        </para>
+
+        <para>
+            But this adds one case which you have to be aware. When you are using an array as
+            haystack then you should wrap it within an <property>'token'</property> key when
+            it could contain only one element.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$valid = new Zend_Validate_Identical(array('token' => 123));
+if ($valid->isValid($input)) {
+    // input appears to be valid
+} else {
+    // input is invalid
+}
+]]></programlisting>
+
+        <para>
+            The above example validates the integer 123. The reason for this special case is, that
+            you can configure the token which has to be used by giving the
+            <property>'token'</property> key.
+        </para>
+
+        <para>
+            So, when your haystack contains one element and this element is named
+            <property>'token'</property> then you have to wrap it like shown in the example below.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$valid = new Zend_Validate_Identical(array('token' => array('token' => 123)));
+if ($valid->isValid($input)) {
+    // input appears to be valid
+} else {
+    // input is invalid
+}
+]]></programlisting>
+    </sect3>
+</sect2>
+<!--
+vim:se ts=4 sw=4 et:
+-->

documentation/manual/en/module_specs/Zend_Validate-Set.xml

@@ -166,33 +166,7 @@ if ($validator->isValid($iban)) {
         </para>
     </sect2>
 
-    <sect2 id="zend.validate.set.identical">
-        <title>Identical</title>
-        <para>
-            Returns <constant>TRUE</constant> if and only if a given token is identical
-            with <varname>$value</varname>. This validator can handle any given type.
-        </para>
-
-        <para>
-            The token to validate against can eighter be set as parameter at initiation,
-            or by using the <methodname>setToken()</methodname> method.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Setting the token at initiation
-$validator = new Zend_Validate_Identical(array('one' => 'two'));
-if ($validator->isValid(array('one' => 'two'))) { // token valid
-    // do something
-}
-
-// Setting the token by using setToken()
-$validator->setToken(true);
-if ($validator->isValid(1)) { // token invalid
-    // do something
-}
-]]></programlisting>
-    </sect2>
-
+    <xi:include href="Zend_Validate-Identical.xml" />
     <xi:include href="Zend_Validate-InArray.xml" />
 
     <sect2 id="zend.validate.set.int">

library/Zend/Validate/Identical.php

@@ -70,12 +70,10 @@ class Zend_Validate_Identical extends Zend_Validate_Abstract
     {
         if ($token instanceof Zend_Config) {
             $token = $token->toArray();
-            if (array_key_exists('token', $token)) {
-                $token = $token['token'];
-            } else {
-                require_once 'Zend/Validate/Exception.php';
-                throw new Zend_Validate_Exception("Missing option 'token'");
-            }
+        }
+
+        if (is_array($token) && (count($token) == 1) && array_key_exists('token', $token)) {
+            $token = $token['token'];
         }
 
         if (null !== $token) {

tests/Zend/Validate/IdenticalTest.php

@@ -138,6 +138,13 @@ class Zend_Validate_IdenticalTest extends PHPUnit_Framework_TestCase
         $this->assertTrue($this->validator->isValid(array('one' => 'two', 'three')));
         $this->assertFalse($this->validator->isValid(array()));
     }
+
+    public function testValidatingTokenArray()
+    {
+        $validator = new Zend_Validate_Identical(array('token' => 123));
+        $this->assertTrue($validator->isValid(123));
+        $this->assertFalse($validator->isValid(array('token' => 123)));
+    }
 }
 
 // Call Zend_Validate_IdenticalTest::main() if this source file is executed directly.