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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.hostname">
   4     <title>Hostname</title>
   5
   6     <para>
   7         <classname>Zend_Validate_Hostname</classname> allows you to validate a hostname against a
   8         set of known specifications. It is possible to check for three different types of hostnames:
   9         a <acronym>DNS</acronym> Hostname (i.e. <filename>domain.com</filename>), IP address (i.e.
  10         1.2.3.4), and Local hostnames (i.e. localhost). By default only <acronym>DNS</acronym>
  11         hostnames are matched.
  12     </para>
  13
  14     <sect3 id="zend.validate.set.hostname.options">
  15         <title>Supported options for Zend_Validate_Hostname</title>
  16
  17         <para>
  18             The following options are supported for <classname>Zend_Validate_Hostname</classname>:
  19         </para>
  20
  21         <itemizedlist>
  22             <listitem>
  23                 <para>
  24                     <emphasis><property>allow</property></emphasis>: Defines the sort of hostname
  25                     which is allowed to be used. See <link
  26                         linkend="zend.validate.set.hostname.types">Hostname types</link> for
  27                     details.
  28                 </para>
  29             </listitem>
  30
  31             <listitem>
  32                 <para>
  33                     <emphasis><property>idn</property></emphasis>: Defines if <acronym>IDN</acronym>
  34                     domains are allowed or not. This option defaults to <constant>TRUE</constant>.
  35                 </para>
  36             </listitem>
  37
  38             <listitem>
  39                 <para>
  40                     <emphasis><property>ip</property></emphasis>: Allows to define a own IP
  41                     validator. This option defaults to a new instance of
  42                     <classname>Zend_Validate_Ip</classname>.
  43                 </para>
  44             </listitem>
  45
  46             <listitem>
  47                 <para>
  48                     <emphasis><property>tld</property></emphasis>: Defines if
  49                     <acronym>TLD</acronym>s are validated. This option defaults to
  50                     <constant>TRUE</constant>.
  51                 </para>
  52             </listitem>
  53         </itemizedlist>
  54     </sect3>
  55
  56     <sect3 id="zend.validate.set.hostname.basic">
  57         <title>Basic usage</title>
  58
  59         <para>
  60             A basic example of usage is below:
  61         </para>
  62
  63         <programlisting language="php"><![CDATA[
  64 $validator = new Zend_Validate_Hostname();
  65 if ($validator->isValid($hostname)) {
  66     // hostname appears to be valid
  67 } else {
  68     // hostname is invalid; print the reasons
  69     foreach ($validator->getMessages() as $message) {
  70         echo "$message\n";
  71     }
  72 }
  73 ]]></programlisting>
  74
  75         <para>
  76             This will match the hostname <varname>$hostname</varname> and on failure populate
  77             <methodname>getMessages()</methodname> with useful error messages.
  78         </para>
  79     </sect3>
  80
  81     <sect3 id="zend.validate.set.hostname.types">
  82         <title>Validating different types of hostnames</title>
  83
  84         <para>
  85             You may find you also want to match IP addresses, Local hostnames, or a combination of
  86             all allowed types. This can be done by passing a parameter to
  87             <classname>Zend_Validate_Hostname</classname> when you instantiate it. The parameter
  88             should be an integer which determines what types of hostnames are allowed. You are
  89             encouraged to use the <classname>Zend_Validate_Hostname</classname> constants to do
  90             this.
  91         </para>
  92
  93         <para>
  94             The <classname>Zend_Validate_Hostname</classname> constants are:
  95             <constant>ALLOW_DNS</constant> to allow only
  96             <acronym>DNS</acronym> hostnames, <constant>ALLOW_IP</constant> to allow IP addresses,
  97             <constant>ALLOW_LOCAL</constant> to allow local network names, and
  98             <constant>ALLOW_ALL</constant> to allow all three types. To just check for IP addresses
  99             you can use the example below:
 100         </para>
 101
 102         <programlisting language="php"><![CDATA[
 103 $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_IP);
 104 if ($validator->isValid($hostname)) {
 105     // hostname appears to be valid
 106 } else {
 107     // hostname is invalid; print the reasons
 108     foreach ($validator->getMessages() as $message) {
 109         echo "$message\n";
 110     }
 111 }
 112 ]]></programlisting>
 113
 114         <para>
 115             As well as using <constant>ALLOW_ALL</constant> to accept all hostnames types you can
 116             combine these types to allow for combinations. For example, to accept
 117             <acronym>DNS</acronym> and Local hostnames instantiate your
 118             <classname>Zend_Validate_Hostname</classname> object as so:
 119         </para>
 120
 121         <programlisting language="php"><![CDATA[
 122 $validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_DNS |
 123                                         Zend_Validate_Hostname::ALLOW_IP);
 124 ]]></programlisting>
 125     </sect3>
 126
 127     <sect3 id="zend.validate.set.hostname.idn">
 128         <title>Validating International Domains Names</title>
 129
 130         <para>
 131             Some Country Code Top Level Domains (ccTLDs), such as 'de' (Germany), support
 132             international characters in domain names. These are known as International Domain Names
 133             (<acronym>IDN</acronym>). These domains can be matched by
 134             <classname>Zend_Validate_Hostname</classname> via extended characters that are used in
 135             the validation process.
 136         </para>
 137
 138         <note>
 139             <title>IDN domains</title>
 140
 141             <para>
 142                 Until now more than 50 ccTLDs support <acronym>IDN</acronym> domains.
 143             </para>
 144         </note>
 145
 146         <para>
 147             To match an <acronym>IDN</acronym> domain it's as simple as just using the standard
 148             Hostname validator since <acronym>IDN</acronym> matching is enabled by default. If you
 149             wish to disable <acronym>IDN</acronym> validation this can be done by either passing a
 150             parameter to the <classname>Zend_Validate_Hostname</classname> constructor or via the
 151             <methodname>setValidateIdn()</methodname> method.
 152         </para>
 153
 154         <para>
 155             You can disable <acronym>IDN</acronym> validation by passing a second parameter to the
 156             <classname>Zend_Validate_Hostname</classname> constructor in the following way.
 157         </para>
 158
 159         <programlisting language="php"><![CDATA[
 160 $validator =
 161     new Zend_Validate_Hostname(
 162         array(
 163             'allow' => Zend_Validate_Hostname::ALLOW_DNS,
 164             'idn'   => false
 165         )
 166     );
 167 ]]></programlisting>
 168
 169         <para>
 170             Alternatively you can either pass <constant>TRUE</constant> or
 171             <constant>FALSE</constant> to <methodname>setValidateIdn()</methodname> to enable or
 172             disable <acronym>IDN</acronym> validation. If you are trying to match an
 173             <acronym>IDN</acronym> hostname which isn't currently supported it is likely it will
 174             fail validation if it has any international characters in it. Where a ccTLD file doesn't
 175             exist in <filename>Zend/Validate/Hostname</filename> specifying the additional
 176             characters a normal hostname validation is performed.
 177         </para>
 178
 179         <note>
 180             <title>IDN validation</title>
 181
 182             <para>
 183                 Please note that <acronym>IDN</acronym>s are only validated if you allow
 184                 <acronym>DNS</acronym> hostnames to be validated.
 185             </para>
 186         </note>
 187     </sect3>
 188
 189     <sect3 id="zend.validate.set.hostname.tld">
 190         <title>Validating Top Level Domains</title>
 191
 192         <para>
 193             By default a hostname will be checked against a list of known <acronym>TLD</acronym>s.
 194             If this functionality is not required it can be disabled in much the same way as
 195             disabling <acronym>IDN</acronym> support. You can disable <acronym>TLD</acronym>
 196             validation by passing a third parameter to the
 197             <classname>Zend_Validate_Hostname</classname> constructor. In the example below we are
 198             supporting <acronym>IDN</acronym> validation via the second parameter.
 199         </para>
 200
 201         <programlisting language="php"><![CDATA[
 202 $validator =
 203     new Zend_Validate_Hostname(
 204         array(
 205             'allow' => Zend_Validate_Hostname::ALLOW_DNS,
 206             'idn'   => true,
 207             'tld'   => false
 208         )
 209     );
 210 ]]></programlisting>
 211
 212         <para>
 213             Alternatively you can either pass <constant>TRUE</constant> or
 214             <constant>FALSE</constant> to <methodname>setValidateTld()</methodname> to enable or
 215             disable <acronym>TLD</acronym> validation.
 216         </para>
 217
 218         <note>
 219             <title>TLD validation</title>
 220
 221             <para>
 222                 Please note <acronym>TLD</acronym>s are only validated if you allow
 223                 <acronym>DNS</acronym> hostnames to be validated.
 224             </para>
 225         </note>
 226     </sect3>
 227 </sect2>
 228 <!--
 229 vim:se ts=4 sw=4 et:
 230 -->