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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.callback">
   4     <title>Callback</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Callback</classname> allows you to provide a callback with which to
   8         validate a given value.
   9     </para>
  10
  11     <sect3 id="zend.validate.set.callback.options">
  12         <title>Supported options for Zend_Validate_Callback</title>
  13
  14         <para>
  15             The following options are supported for <classname>Zend_Validate_Callback</classname>:
  16         </para>
  17
  18         <itemizedlist>
  19             <listitem>
  20                 <para>
  21                     <emphasis><property>callback</property></emphasis>: Sets the callback which will
  22                     be called for the validation.
  23                 </para>
  24             </listitem>
  25
  26             <listitem>
  27                 <para>
  28                     <emphasis><property>options</property></emphasis>: Sets the additional options
  29                     which will be given to the callback.
  30                 </para>
  31             </listitem>
  32         </itemizedlist>
  33     </sect3>
  34
  35     <sect3 id="zend.validate.set.callback.basic">
  36         <title>Basic usage</title>
  37
  38         <para>
  39             The simplest usecase is to have a single function and use it as a callback. Let's expect
  40             we have the following function.
  41         </para>
  42
  43         <programlisting language="php"><![CDATA[
  44 function myMethod($value)
  45 {
  46     // some validation
  47     return true;
  48 }
  49 ]]></programlisting>
  50
  51         <para>
  52             To use it within <classname>Zend_Validate_Callback</classname> you just have to call it
  53             this way:
  54         </para>
  55
  56         <programlisting language="php"><![CDATA[
  57 $valid = new Zend_Validate_Callback('myMethod');
  58 if ($valid->isValid($input)) {
  59     // input appears to be valid
  60 } else {
  61     // input is invalid
  62 }
  63 ]]></programlisting>
  64     </sect3>
  65
  66     <sect3 id="zend.validate.set.callback.closure">
  67         <title>Usage with closures</title>
  68
  69         <para>
  70             <acronym>PHP</acronym> 5.3 introduces <ulink
  71                 url="http://php.net/functions.anonymous">closures</ulink>, which are basically
  72             self-contained or <emphasis>anonymous</emphasis> functions. <acronym>PHP</acronym>
  73             considers closures another form of callback, and, as such, may be used with
  74             <classname>Zend_Validate_Callback</classname>. As an example:
  75         </para>
  76
  77         <programlisting language="php"><![CDATA[
  78 $valid = new Zend_Validate_Callback(function($value){
  79     // some validation
  80     return true;
  81 });
  82
  83 if ($valid->isValid($input)) {
  84     // input appears to be valid
  85 } else {
  86     // input is invalid
  87 }
  88 ]]></programlisting>
  89     </sect3>
  90
  91     <sect3 id="zend.validate.set.callback.class">
  92         <title>Usage with class-based callbacks</title>
  93
  94         <para>
  95             Of course it's also possible to use a class method as callback. Let's expect we have
  96             the following class method:
  97         </para>
  98
  99         <programlisting language="php"><![CDATA[
 100 class MyClass
 101 {
 102     public function myMethod($value)
 103     {
 104         // some validation
 105         return true;
 106     }
 107 }
 108 ]]></programlisting>
 109
 110         <para>
 111             The definition of the callback is in this case almost the same. You have just to create
 112             an instance of the class before the method and create an array describing the callback:
 113         </para>
 114
 115         <programlisting language="php"><![CDATA[
 116 $object = new MyClass;
 117 $valid = new Zend_Validate_Callback(array($object, 'myMethod'));
 118 if ($valid->isValid($input)) {
 119     // input appears to be valid
 120 } else {
 121     // input is invalid
 122 }
 123 ]]></programlisting>
 124
 125         <para>
 126             You may also define a static method as a callback. Consider the following class
 127             definition and validator usage:
 128         </para>
 129
 130         <programlisting language="php"><![CDATA[
 131 class MyClass
 132 {
 133     public static function test($value)
 134     {
 135         // some validation
 136         return true;
 137     }
 138 }
 139
 140 $valid = new Zend_Validate_Callback(array('MyClass', 'test'));
 141 if ($valid->isValid($input)) {
 142     // input appears to be valid
 143 } else {
 144     // input is invalid
 145 }
 146 ]]></programlisting>
 147
 148         <para>
 149             Finally, if you are using <acronym>PHP</acronym> 5.3, you may define the magic method
 150             <methodname>__invoke()</methodname> in your class. If you do so, simply providing an
 151             instance of the class as the callback will also work:
 152         </para>
 153
 154         <programlisting language="php"><![CDATA[
 155 class MyClass
 156 {
 157     public function __invoke($value)
 158     {
 159         // some validation
 160         return true;
 161     }
 162 }
 163
 164 $object = new MyClass();
 165 $valid = new Zend_Validate_Callback($object);
 166 if ($valid->isValid($input)) {
 167     // input appears to be valid
 168 } else {
 169     // input is invalid
 170 }
 171 ]]></programlisting>
 172     </sect3>
 173
 174     <sect3 id="zend.validate.set.callback.options2">
 175         <title>Adding options</title>
 176
 177         <para>
 178             <classname>Zend_Validate_Callback</classname> also allows the usage of options which
 179             are provided as additional arguments to the callback.
 180         </para>
 181
 182         <para>
 183             Consider the following class and method definition:
 184         </para>
 185
 186         <programlisting language="php"><![CDATA[
 187 class MyClass
 188 {
 189     function myMethod($value, $option)
 190     {
 191         // some validation
 192         return true;
 193     }
 194 }
 195 ]]></programlisting>
 196
 197         <para>
 198             There are two ways to inform the validator of additional options: pass them in the
 199             constructor, or pass them to the <methodname>setOptions()</methodname> method.
 200         </para>
 201
 202         <para>
 203             To pass them to the constructor, you would need to pass an array containing two keys,
 204             "callback" and "options":
 205         </para>
 206
 207         <programlisting language="php"><![CDATA[
 208 $valid = new Zend_Validate_Callback(array(
 209     'callback' => array('MyClass', 'myMethod'),
 210     'options'  => $option,
 211 ));
 212
 213 if ($valid->isValid($input)) {
 214     // input appears to be valid
 215 } else {
 216     // input is invalid
 217 }
 218 ]]></programlisting>
 219
 220         <para>
 221             Otherwise, you may pass them to the validator after instantiation:
 222         </para>
 223
 224         <programlisting language="php"><![CDATA[
 225 $valid = new Zend_Validate_Callback(array('MyClass', 'myMethod'));
 226 $valid->setOptions($option);
 227
 228 if ($valid->isValid($input)) {
 229     // input appears to be valid
 230 } else {
 231     // input is invalid
 232 }
 233 ]]></programlisting>
 234
 235         <para>
 236             When there are additional values given to <methodname>isValid()</methodname> then these
 237             values will be added immediately after <varname>$value</varname>.
 238         </para>
 239
 240         <programlisting language="php"><![CDATA[
 241 $valid = new Zend_Validate_Callback(array('MyClass', 'myMethod'));
 242 $valid->setOptions($option);
 243
 244 if ($valid->isValid($input, $additional)) {
 245     // input appears to be valid
 246 } else {
 247     // input is invalid
 248 }
 249 ]]></programlisting>
 250
 251         <para>
 252             When making the call to the callback, the value to be validated will always be passed as
 253             the first argument to the callback followed by all other values given to
 254             <methodname>isValid()</methodname>; all other options will follow it. The amount and
 255             type of options which can be used is not limited.
 256         </para>
 257     </sect3>
 258 </sect2>
 259 <!--
 260 vim:se ts=4 sw=4 et:
 261 -->