documentation/manual/en/module_specs/Zend_Validate.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.validate.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         The <classname>Zend_Validate</classname> component provides a set of commonly needed
   8         validators. It also provides a simple validator chaining mechanism by
   9         which multiple validators may be applied to a single datum in a
  10         user-defined order.
  11     </para>
  12
  13     <sect2 id="zend.validate.introduction.definition">
  14         <title>What is a validator?</title>
  15
  16         <para>
  17             A validator examines its input with respect to some requirements
  18             and produces a boolean result - whether the input successfully
  19             validates against the requirements. If the input does not meet the
  20             requirements, a validator may additionally provide information
  21             about which requirement(s) the input does not meet.
  22         </para>
  23
  24         <para>
  25             For example, a web application might require that a username be
  26             between six and twelve characters in length and may only contain
  27             alphanumeric characters. A validator can be used for ensuring that
  28             usernames meet these requirements. If a chosen username does not
  29             meet one or both of the requirements, it would be useful to know
  30             which of the requirements the username fails to meet.
  31         </para>
  32     </sect2>
  33
  34     <sect2 id="zend.validate.introduction.using">
  35         <title>Basic usage of validators</title>
  36
  37         <para>
  38             Having defined validation in this way provides the foundation for
  39             <classname>Zend_Validate_Interface</classname>, which defines two methods,
  40             <methodname>isValid()</methodname> and <methodname>getMessages()</methodname>. The
  41             <methodname>isValid()</methodname> method performs validation upon the provided
  42             value, returning <constant>TRUE</constant> if and only if the value passes
  43             against the validation criteria.
  44         </para>
  45
  46         <para>
  47             If <methodname>isValid()</methodname> returns <constant>FALSE</constant>, the
  48             <methodname>getMessages()</methodname> returns an array of messages explaining
  49             the reason(s) for validation failure. The array keys are short
  50             strings that identify the reasons for validation failure, and the
  51             array values are the corresponding human-readable string messages.
  52             The keys and values are class-dependent; each validation class
  53             defines its own set of validation failure messages and the unique
  54             keys that identify them. Each class also has a const
  55             definition that matches each identifier for a validation failure
  56             cause.
  57         </para>
  58
  59         <note>
  60             <para>
  61                 The <methodname>getMessages()</methodname> methods return validation
  62                 failure information only for the most recent
  63                 <methodname>isValid()</methodname> call. Each call to
  64                 <methodname>isValid()</methodname> clears any messages and errors caused by
  65                 a previous <methodname>isValid()</methodname> call, because it's likely
  66                 that each call to <methodname>isValid()</methodname> is made for a
  67                 different input value.
  68             </para>
  69         </note>
  70
  71         <para>
  72             The following example illustrates validation of an e-mail address:
  73         </para>
  74
  75         <programlisting language="php"><![CDATA[
  76 $validator = new Zend_Validate_EmailAddress();
  77
  78 if ($validator->isValid($email)) {
  79     // email appears to be valid
  80 } else {
  81     // email is invalid; print the reasons
  82     foreach ($validator->getMessages() as $messageId => $message) {
  83         echo "Validation failure '$messageId': $message\n";
  84     }
  85 }
  86 ]]></programlisting>
  87     </sect2>
  88
  89     <sect2 id="zend.validate.introduction.messages">
  90         <title>Customizing messages</title>
  91
  92         <para>
  93             Validate classes provide a <methodname>setMessage()</methodname> method with
  94             which you can specify the format of a message returned by
  95             <methodname>getMessages()</methodname> in case of validation failure. The
  96             first argument of this method is a string containing the error
  97             message. You can include tokens in this string which will be
  98             substituted with data relevant to the validator. The token
  99             <emphasis>%value%</emphasis> is supported by all validators; this is
 100             substituted with the value you passed to <methodname>isValid()</methodname>.
 101             Other tokens may be supported on a case-by-case basis in each
 102             validation class. For example, <emphasis>%max%</emphasis> is a token
 103             supported by <classname>Zend_Validate_LessThan</classname>.
 104             The <methodname>getMessageVariables()</methodname> method returns an array
 105             of variable tokens supported by the validator.
 106         </para>
 107
 108         <para>
 109             The second optional argument is a string that identifies the
 110             validation failure message template to be set, which is useful when
 111             a validation class defines more than one cause for failure. If you
 112             omit the second argument, <methodname>setMessage()</methodname> assumes the
 113             message you specify should be used for the first message template
 114             declared in the validation class. Many validation classes only have
 115             one error message template defined, so there is no need to specify
 116             which message template you are changing.
 117         </para>
 118
 119         <programlisting language="php"><![CDATA[
 120 $validator = new Zend_Validate_StringLength(8);
 121
 122 $validator->setMessage(
 123     'The string \'%value%\' is too short; it must be at least %min% ' .
 124     'characters',
 125     Zend_Validate_StringLength::TOO_SHORT);
 126
 127 if (!$validator->isValid('word')) {
 128     $messages = $validator->getMessages();
 129     echo current($messages);
 130
 131     // "The string 'word' is too short; it must be at least 8 characters"
 132 }
 133 ]]></programlisting>
 134
 135         <para>
 136             You can set multiple messages using the <methodname>setMessages()</methodname>
 137             method. Its argument is an array containing key/message pairs.
 138         </para>
 139
 140         <programlisting language="php"><![CDATA[
 141 $validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
 142
 143 $validator->setMessages( array(
 144     Zend_Validate_StringLength::TOO_SHORT =>
 145         'The string \'%value%\' is too short',
 146     Zend_Validate_StringLength::TOO_LONG  =>
 147         'The string \'%value%\' is too long'
 148 ));
 149 ]]></programlisting>
 150
 151         <para>
 152             If your application requires even greater flexibility with which it
 153             reports validation failures, you can access properties by the same
 154             name as the message tokens supported by a given validation class.
 155             The <property>value</property> property is always available in a validator;
 156             it is the value you specified as the argument of
 157             <methodname>isValid()</methodname>. Other properties may be supported on a
 158             case-by-case basis in each validation class.
 159         </para>
 160
 161         <programlisting language="php"><![CDATA[
 162 $validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
 163
 164 if (!validator->isValid('word')) {
 165     echo 'Word failed: '
 166         . $validator->value
 167         . '; its length is not between '
 168         . $validator->min
 169         . ' and '
 170         . $validator->max
 171         . "\n";
 172 }
 173 ]]></programlisting>
 174     </sect2>
 175
 176     <sect2 id="zend.validate.introduction.static">
 177         <title>Using the static is() method</title>
 178
 179         <para>
 180             If it's inconvenient to load a given validation class and create an
 181             instance of the validator, you can use the static method
 182             <methodname>Zend_Validate::is()</methodname> as an alternative invocation
 183             style. The first argument of this method is a data input value,
 184             that you would pass to the <methodname>isValid()</methodname> method. The
 185             second argument is a string, which corresponds to the basename of
 186             the validation class, relative to the <classname>Zend_Validate</classname>
 187             namespace. The <methodname>is()</methodname> method automatically loads the
 188             class, creates an instance, and applies the <methodname>isValid()</methodname>
 189             method to the data input.
 190         </para>
 191
 192         <programlisting language="php"><![CDATA[
 193 if (Zend_Validate::is($email, 'EmailAddress')) {
 194     // Yes, email appears to be valid
 195 }
 196 ]]></programlisting>
 197
 198         <para>
 199             You can also pass an array of constructor arguments, if they
 200             are needed for the validator.
 201         </para>
 202
 203         <programlisting language="php"><![CDATA[
 204 if (Zend_Validate::is($value, 'Between', array('min' => 1, 'max' => 12))) {
 205     // Yes, $value is between 1 and 12
 206 }
 207 ]]></programlisting>
 208
 209         <para>
 210             The <methodname>is()</methodname> method returns a boolean value, the same as
 211             the <methodname>isValid()</methodname> method. When using the static
 212             <methodname>is()</methodname> method, validation failure messages are not
 213             available.
 214         </para>
 215
 216         <para>
 217             The static usage can be convenient for invoking a validator ad hoc,
 218             but if you have the need to run a validator for multiple inputs,
 219             it's more efficient to use the non-static usage, creating an
 220             instance of the validator object and calling its
 221             <methodname>isValid()</methodname> method.
 222         </para>
 223
 224         <para>
 225             Also, the <classname>Zend_Filter_Input</classname> class allows you to
 226             instantiate and run multiple filter and validator classes on demand
 227             to process sets of input data. See
 228             <xref linkend="zend.filter.input" />.
 229         </para>
 230
 231         <sect3 id="zend.validate.introduction.static.namespaces">
 232             <title>Namespaces</title>
 233
 234             <para>
 235                 When working with self defined validators you can give a fourth parameter
 236                 to <methodname>Zend_Validate::is()</methodname> which is the namespace
 237                 where your validator can be found.
 238             </para>
 239
 240             <programlisting language="php"><![CDATA[
 241 if (Zend_Validate::is($value, 'MyValidator', array('min' => 1, 'max' => 12),
 242                       array('FirstNamespace', 'SecondNamespace')) {
 243     // Yes, $value is ok
 244 }
 245 ]]></programlisting>
 246
 247             <para>
 248                 <classname>Zend_Validate</classname> allows also to set namespaces as default.
 249                 This means that you can set them once in your bootstrap and have not to give
 250                 them again for each call of <methodname>Zend_Validate::is()</methodname>. The
 251                 following code snippet is identical to the above one.
 252             </para>
 253
 254             <programlisting language="php"><![CDATA[
 255 Zend_Validate::setDefaultNamespaces(array('FirstNamespace', 'SecondNamespace'));
 256 if (Zend_Validate::is($value, 'MyValidator', array('min' => 1, 'max' => 12)) {
 257     // Yes, $value is ok
 258 }
 259
 260 if (Zend_Validate::is($value,
 261                       'OtherValidator',
 262                       array('min' => 1, 'max' => 12)) {
 263     // Yes, $value is ok
 264 }
 265 ]]></programlisting>
 266
 267             <para>
 268                 For your convenience there are following methods which allow the handling of
 269                 namespaces:
 270             </para>
 271
 272             <itemizedlist>
 273                 <listitem>
 274                     <para>
 275                         <emphasis><methodname>Zend_Validate::getDefaultNamespaces()</methodname></emphasis>:
 276                         Returns all set default namespaces as array.
 277                     </para>
 278                 </listitem>
 279
 280                 <listitem>
 281                     <para>
 282                         <emphasis><methodname>Zend_Validate::setDefaultNamespaces()</methodname></emphasis>:
 283                         Sets new default namespaces and overrides any previous set. It accepts
 284                         either a string for a single namespace of an array for multiple namespaces.
 285                     </para>
 286                 </listitem>
 287
 288                 <listitem>
 289                     <para>
 290                         <emphasis><methodname>Zend_Validate::addDefaultNamespaces()</methodname></emphasis>:
 291                         Adds additional namespaces to already set ones. It accepts either a string
 292                         for a single namespace of an array for multiple namespaces.
 293                     </para>
 294                 </listitem>
 295
 296                 <listitem>
 297                     <para>
 298                         <emphasis><methodname>Zend_Validate::hasDefaultNamespaces()</methodname></emphasis>:
 299                         Returns <constant>TRUE</constant> when one or more default namespaces are
 300                         set, and <constant>FALSE</constant> when no default namespaces are set.
 301                     </para>
 302                 </listitem>
 303             </itemizedlist>
 304         </sect3>
 305     </sect2>
 306
 307     <sect2 id="zend.validate.introduction.translation">
 308         <title>Translating messages</title>
 309
 310         <para>
 311             Validate classes provide a <methodname>setTranslator()</methodname> method with
 312             which you can specify a instance of <classname>Zend_Translate</classname> which
 313             will translate the messages in case of a validation failure. The
 314             <methodname>getTranslator()</methodname> method returns the set translator instance.
 315         </para>
 316
 317         <programlisting language="php"><![CDATA[
 318 $validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
 319 $translate = new Zend_Translate(
 320     array(
 321         'adapter' => 'array',
 322         'content' => array(
 323             Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''
 324         ),
 325         'locale' => 'en'
 326     )
 327 );
 328
 329 $validator->setTranslator($translate);
 330 ]]></programlisting>
 331
 332         <para>
 333             With the static <methodname>setDefaultTranslator()</methodname> method you can set
 334             a instance of <classname>Zend_Translate</classname> which will be used for all
 335             validation classes, and can be retrieved with
 336             <methodname>getDefaultTranslator()</methodname>. This prevents you from setting a
 337             translator manually for all validator classes, and simplifies your code.
 338         </para>
 339
 340         <programlisting language="php"><![CDATA[
 341 $translate = new Zend_Translate(
 342     array(
 343         'adapter' => 'array',
 344         'content' => array(
 345             Zend_Validate_StringLength::TOO_SHORT => 'Translated \'%value%\''
 346         ),
 347         'locale' => 'en'
 348     )
 349 );
 350 Zend_Validate::setDefaultTranslator($translate);
 351 ]]></programlisting>
 352
 353         <note>
 354             <para>
 355                 When you have set an application wide locale within your registry, then this
 356                 locale will be used as default translator.
 357             </para>
 358         </note>
 359
 360         <para>
 361             Sometimes it is necessary to disable the translator within a validator.
 362             To archive this you can use the <methodname>setDisableTranslator()</methodname> method,
 363             which accepts a boolean parameter, and <methodname>translatorIsDisabled()</methodname>
 364             to get the set value.
 365         </para>
 366
 367         <programlisting language="php"><![CDATA[
 368 $validator = new Zend_Validate_StringLength(array('min' => 8, 'max' => 12));
 369 if (!$validator->isTranslatorDisabled()) {
 370     $validator->setDisableTranslator();
 371 }
 372 ]]></programlisting>
 373
 374         <para>
 375             It is also possible to use a translator instead of setting own messages with
 376             <methodname>setMessage()</methodname>. But doing so, you should keep in mind, that the
 377             translator works also on messages you set your own.
 378         </para>
 379     </sect2>
 380 </sect1>
 381 <!--
 382 vim:se ts=4 sw=4 et:
 383 -->