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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.identical">
   4     <title>Identical</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Identical</classname> allows you to validate if a given value is
   8         identical with an set haystack.
   9     </para>
  10
  11     <sect3 id="zend.validate.set.identical.basic">
  12         <title>Basic usage</title>
  13
  14         <para>
  15             To validate if two values are identical you need to set the origin value as haystack.
  16             See the following example which validates two strings.
  17         </para>
  18
  19         <programlisting language="php"><![CDATA[
  20 $valid = new Zend_Validate_Identical('origin');
  21 if ($valid->isValid($value) {
  22     return true;
  23 }
  24 ]]></programlisting>
  25
  26         <para>
  27             The validation will only then return <constant>TRUE</constant> when both values are
  28             100% identical. In our example, when <varname>$value</varname> is 'origin'.
  29         </para>
  30
  31         <para>
  32             You can set the wished token also afterwards by using the method
  33             <methodname>setToken()</methodname> and <methodname>getToken()</methodname> to get
  34             the actual set token.
  35         </para>
  36     </sect3>
  37
  38     <sect3 id="zend.validate.set.identical.types">
  39         <title>Identical objects</title>
  40
  41         <para>
  42             Of course <classname>Zend_Validate_Identical</classname> can not only validate strings,
  43             but also any other variable type like Boolean, Integer, Float, Array or even Objects.
  44             As already noted Haystack and Value must be identical.
  45         </para>
  46
  47         <programlisting language="php"><![CDATA[
  48 $valid = new Zend_Validate_Identical(123);
  49 if ($valid->isValid($input)) {
  50     // input appears to be valid
  51 } else {
  52     // input is invalid
  53 }
  54 ]]></programlisting>
  55
  56         <note>
  57             <title>Type comparison</title>
  58
  59             <para>
  60                 You should be aware that also the type of a variable is used for validation.
  61                 This means that the string <emphasis>'3'</emphasis> is not identical with the
  62                 integer <emphasis>3</emphasis>.
  63             </para>
  64
  65             <para>
  66                 This is also the case for Form Elements. They are objects or arrays. So you can't
  67                 simply compare a Textfield which contains a password with an textual password
  68                 from another source. The Element itself is given as array which also contains
  69                 additional informations.
  70             </para>
  71         </note>
  72     </sect3>
  73
  74     <sect3 id="zend.validate.set.identical.configuration">
  75         <title>Configuration</title>
  76
  77         <para>
  78             As all other validators also <classname>Zend_Validate_Identical</classname> supports
  79             the usage of configuration settings as input parameter. This means that you can
  80             configure this validator with an <classname>Zend_Config</classname> object.
  81         </para>
  82
  83         <para>
  84             But this adds one case which you have to be aware. When you are using an array as
  85             haystack then you should wrap it within an <property>'token'</property> key when
  86             it could contain only one element.
  87         </para>
  88
  89         <programlisting language="php"><![CDATA[
  90 $valid = new Zend_Validate_Identical(array('token' => 123));
  91 if ($valid->isValid($input)) {
  92     // input appears to be valid
  93 } else {
  94     // input is invalid
  95 }
  96 ]]></programlisting>
  97
  98         <para>
  99             The above example validates the integer 123. The reason for this special case is, that
 100             you can configure the token which has to be used by giving the
 101             <property>'token'</property> key.
 102         </para>
 103
 104         <para>
 105             So, when your haystack contains one element and this element is named
 106             <property>'token'</property> then you have to wrap it like shown in the example below.
 107         </para>
 108
 109         <programlisting language="php"><![CDATA[
 110 $valid = new Zend_Validate_Identical(array('token' => array('token' => 123)));
 111 if ($valid->isValid($input)) {
 112     // input appears to be valid
 113 } else {
 114     // input is invalid
 115 }
 116 ]]></programlisting>
 117     </sect3>
 118 </sect2>
 119 <!--
 120 vim:se ts=4 sw=4 et:
 121 -->