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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.in_array">
   4     <title>InArray</title>
   5
   6     <para>
   7         <classname>Zend_Validate_InArray</classname> allows you to validate if a given value is
   8         contained within an array. It is also able to validate multidimensional arrays.
   9     </para>
  10
  11     <sect3 id="zend.validate.set.in_array.options">
  12         <title>Supported options for Zend_Validate_InArray</title>
  13
  14         <para>
  15             The following options are supported for <classname>Zend_Validate_InArray</classname>:
  16         </para>
  17
  18         <itemizedlist>
  19             <listitem>
  20                 <para>
  21                     <emphasis><property>haystack</property></emphasis>: Sets the haystack for the
  22                     validation.
  23                 </para>
  24             </listitem>
  25
  26             <listitem>
  27                 <para>
  28                     <emphasis><property>recursive</property></emphasis>: Defines if the validation
  29                     should be done recursive. This option defaults to <constant>FALSE</constant>.
  30                 </para>
  31             </listitem>
  32
  33             <listitem>
  34                 <para>
  35                     <emphasis><property>strict</property></emphasis>: Defines if the validation
  36                     should be done strict. This option defaults to <constant>FALSE</constant>.
  37                 </para>
  38             </listitem>
  39         </itemizedlist>
  40     </sect3>
  41
  42     <sect3 id="zend.validate.set.in_array.basic">
  43         <title>Simple array validation</title>
  44
  45         <para>
  46             The simplest way, is just to give the array which should be searched against at
  47             initiation:
  48         </para>
  49
  50         <programlisting language="php"><![CDATA[
  51 $validator = new Zend_Validate_InArray(array('key' => 'value',
  52                                              'otherkey' => 'othervalue'));
  53 if ($validator->isValid('value')) {
  54     // value found
  55 } else {
  56     // no value found
  57 }
  58 ]]></programlisting>
  59
  60         <para>
  61             This will behave exactly like <acronym>PHP</acronym>'s
  62             <methodname>in_array()</methodname> method.
  63         </para>
  64
  65         <note>
  66             <para>
  67                 Per default this validation is not strict nor can it validate multidimensional
  68                 arrays.
  69             </para>
  70         </note>
  71
  72         <para>
  73             Of course you can give the array to validate against also afterwards by using the
  74             <methodname>setHaystack()</methodname> method. <methodname>getHaystack()</methodname>
  75             returns the actual set haystack array.
  76         </para>
  77
  78         <programlisting language="php"><![CDATA[
  79 $validator = new Zend_Validate_InArray();
  80 $validator->setHaystack(array('key' => 'value', 'otherkey' => 'othervalue'));
  81
  82 if ($validator->isValid('value')) {
  83     // value found
  84 } else {
  85     // no value found
  86 }
  87 ]]></programlisting>
  88     </sect3>
  89
  90     <sect3 id="zend.validate.set.in_array.strict">
  91         <title>Strict array validation</title>
  92
  93         <para>
  94             As mentioned before you can also do a strict validation within the array. Per default
  95             there would be no difference between the integer value <emphasis>0</emphasis> and the
  96             string <emphasis>"0"</emphasis>. When doing a strict validation this difference will
  97             also be validated and only same types are accepted.
  98         </para>
  99
 100         <para>
 101             A strict validation can also be done by using two different ways. At initiation and by
 102             using a method. At initiation you have to give an array with the following structure:
 103         </para>
 104
 105         <programlisting language="php"><![CDATA[
 106 $validator = new Zend_Validate_InArray(
 107     array(
 108         'haystack' => array('key' => 'value', 'otherkey' => 'othervalue'),
 109         'strict'   => true
 110     )
 111 );
 112
 113 if ($validator->isValid('value')) {
 114     // value found
 115 } else {
 116     // no value found
 117 }
 118 ]]></programlisting>
 119
 120         <para>
 121             The <emphasis>haystack</emphasis> key contains your array to validate against. And by
 122             setting the <emphasis>strict</emphasis> key to <constant>TRUE</constant>, the validation
 123             is done by using a strict type check.
 124         </para>
 125
 126         <para>
 127             Of course you can also use the <methodname>setStrict()</methodname> method to change
 128             this setting afterwards and <methodname>getStrict()</methodname> to get the actual set
 129             state.
 130         </para>
 131
 132         <note>
 133             <para>
 134                 Note that the <emphasis>strict</emphasis> setting is per default
 135                 <constant>FALSE</constant>.
 136             </para>
 137         </note>
 138     </sect3>
 139
 140     <sect3 id="zend.validate.set.in_array.recursive">
 141         <title>Recursive array validation</title>
 142
 143         <para>
 144             In addition to <acronym>PHP</acronym>'s <methodname>in_array()</methodname> method
 145             this validator can also be used to validate multidimensional arrays.
 146         </para>
 147
 148         <para>
 149             To validate multidimensional arrays you have to set the <emphasis>recursive</emphasis>
 150             option.
 151         </para>
 152
 153         <programlisting language="php"><![CDATA[
 154 $validator = new Zend_Validate_InArray(
 155     array(
 156         'haystack' => array(
 157             'firstDimension' => array('key' => 'value',
 158                                       'otherkey' => 'othervalue'),
 159             'secondDimension' => array('some' => 'real',
 160                                        'different' => 'key')),
 161         'recursive' => true
 162     )
 163 );
 164
 165 if ($validator->isValid('value')) {
 166     // value found
 167 } else {
 168     // no value found
 169 }
 170 ]]></programlisting>
 171
 172         <para>
 173             Your array will then be validated recursive to see if the given value is contained.
 174             Additionally you could use <methodname>setRecursive()</methodname> to set this option
 175             afterwards and <methodname>getRecursive()</methodname> to retrieve it.
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 $validator = new Zend_Validate_InArray(
 180     array(
 181         'firstDimension' => array('key' => 'value',
 182                                   'otherkey' => 'othervalue'),
 183         'secondDimension' => array('some' => 'real',
 184                                    'different' => 'key')
 185     )
 186 );
 187 $validator->setRecursive(true);
 188
 189 if ($validator->isValid('value')) {
 190     // value found
 191 } else {
 192     // no value found
 193 }
 194 ]]></programlisting>
 195
 196         <note>
 197             <title>Default setting for recursion</title>
 198
 199             <para>
 200                 Per default the recursive validation is turned off.
 201             </para>
 202         </note>
 203
 204         <note>
 205             <title>Option keys within the haystack</title>
 206
 207             <para>
 208                 When you are using the keys '<property>haystack</property>',
 209                 '<property>strict</property>' or '<property>recursive</property>' within your
 210                 haystack, then you must wrap the <property>haystack</property> key.
 211             </para>
 212         </note>
 213     </sect3>
 214 </sect2>
 215 <!--
 216 vim:se ts=4 sw=4 et:
 217 -->