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