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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.iban">
   4     <title>Iban</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Iban</classname> validates if a given value could be a
   8         <acronym>IBAN</acronym> number. <acronym>IBAN</acronym> is the abbreviation for
   9         "International Bank Account Number".
  10     </para>
  11
  12     <sect3 id="zend.validate.set.iban.options">
  13         <title>Supported options for Zend_Validate_Iban</title>
  14
  15         <para>
  16             The following options are supported for <classname>Zend_Validate_Iban</classname>:
  17         </para>
  18
  19         <itemizedlist>
  20             <listitem>
  21                 <para>
  22                     <emphasis><property>locale</property></emphasis>: Sets the locale which is used
  23                     to get the <acronym>IBAN</acronym> format for validation.
  24                 </para>
  25             </listitem>
  26         </itemizedlist>
  27     </sect3>
  28
  29     <sect3 id="zend.validate.set.iban.basic">
  30         <title>IBAN validation</title>
  31
  32         <para>
  33             <acronym>IBAN</acronym> numbers are always related to a country. This means that
  34             different countries use different formats for their <acronym>IBAN</acronym> numbers.
  35             This is the reason why <acronym>IBAN</acronym> numbers always need a locale. By knowing
  36             this we already know how to use <classname>Zend_Validate_Iban</classname>.
  37         </para>
  38
  39         <sect4 id="zend.validate.set.iban.basic.application">
  40             <title>Application wide locale</title>
  41
  42             <para>
  43                 We could use the application wide locale. This means that when no option is given at
  44                 initiation, <classname>Zend_Validate_Iban</classname> searches for the application
  45                 wide locale. See the following code snippet:
  46             </para>
  47
  48             <programlisting language="php"><![CDATA[
  49 // within bootstrap
  50 Zend_Registry::set('Zend_Locale', new Zend_Locale('de_AT'));
  51
  52 // within the module
  53 $validator = new Zend_Validate_Iban();
  54
  55 if ($validator->isValid('AT611904300234573201')) {
  56     // IBAN appears to be valid
  57 } else {
  58     // IBAN is not valid
  59 }
  60 ]]></programlisting>
  61
  62             <note>
  63                 <title>Application wide locale</title>
  64
  65                 <para>
  66                     Of course this works only when an application wide locale was set within the
  67                     registry previously. Otherwise <classname>Zend_Locale</classname> will try to
  68                     use the locale which the client sends or, when non has been send, it uses the
  69                     environment locale. Be aware that this can lead to unwanted behaviour within
  70                     the validation.
  71                 </para>
  72             </note>
  73         </sect4>
  74
  75         <sect4 id="zend.validate.set.iban.basic.false">
  76             <title>Ungreedy IBAN validation</title>
  77
  78             <para>
  79                 Sometime it is usefull, just to validate if the given value <emphasis>is</emphasis>
  80                 a <acronym>IBAN</acronym> number or not. This means that you don't want to validate
  81                 it against a defined country. This can be done by using a
  82                 <constant>FALSE</constant> as locale.
  83             </para>
  84
  85             <programlisting language="php"><![CDATA[
  86 $validator = new Zend_Validate_Iban(array('locale' => false));
  87 // Note: you can also set a FALSE as single parameter
  88
  89 if ($validator->isValid('AT611904300234573201')) {
  90     // IBAN appears to be valid
  91 } else {
  92     // IBAN is not valid
  93 }
  94 ]]></programlisting>
  95
  96             <para>
  97                 So <emphasis>any</emphasis> <acronym>IBAN</acronym> number will be valid. Note that
  98                 this should not be done when you accept only accounts from a single country.
  99             </para>
 100         </sect4>
 101
 102         <sect4 id="zend.validate.set.iban.basic.aware">
 103             <title>Region aware IBAN validation</title>
 104
 105             <para>
 106                 To validate against a defined country, you just need to give the wished locale.
 107                 You can do this by the option <property>locale</property> and also afterwards by
 108                 using <methodname>setLocale()</methodname>.
 109             </para>
 110
 111             <programlisting language="php"><![CDATA[
 112 $validator = new Zend_Validate_Iban(array('locale' => 'de_AT'));
 113
 114 if ($validator->isValid('AT611904300234573201')) {
 115     // IBAN appears to be valid
 116 } else {
 117     // IBAN is not valid
 118 }
 119 ]]></programlisting>
 120
 121             <note>
 122                 <title>Use full qualified locales</title>
 123
 124                 <para>
 125                     You must give a full qualified locale, otherwise the country could not be
 126                     detected correct because languages are spoken in multiple countries.
 127                 </para>
 128             </note>
 129         </sect4>
 130     </sect3>
 131 </sect2>
 132 <!--
 133 vim:se ts=4 sw=4 et:
 134 -->