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