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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.validate.set.hostname">
    <title>Hostname</title>

    <para>
        <classname>Zend_Validate_Hostname</classname> allows you to validate a hostname against a
        set of known specifications. It is possible to check for three different types of hostnames:
        a <acronym>DNS</acronym> Hostname (i.e. <filename>domain.com</filename>), IP address (i.e.
        1.2.3.4), and Local hostnames (i.e. localhost). By default only <acronym>DNS</acronym>
        hostnames are matched.
    </para>

    <sect3 id="zend.validate.set.hostname.options">
        <title>Supported options for Zend_Validate_Hostname</title>

        <para>
            The following options are supported for <classname>Zend_Validate_Hostname</classname>:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>allow</property></emphasis>: Defines the sort of hostname
                    which is allowed to be used. See <link
                        linkend="zend.validate.set.hostname.types">Hostname types</link> for
                    details.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>idn</property></emphasis>: Defines if <acronym>IDN</acronym>
                    domains are allowed or not. This option defaults to <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>ip</property></emphasis>: Allows to define a own IP
                    validator. This option defaults to a new instance of
                    <classname>Zend_Validate_Ip</classname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>tld</property></emphasis>: Defines if
                    <acronym>TLD</acronym>s are validated. This option defaults to
                    <constant>TRUE</constant>.
                </para>
            </listitem>
        </itemizedlist>
    </sect3>

    <sect3 id="zend.validate.set.hostname.basic">
        <title>Basic usage</title>

        <para>
            A basic example of usage is below:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Hostname();
if ($validator->isValid($hostname)) {
    // hostname appears to be valid
} else {
    // hostname is invalid; print the reasons
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            This will match the hostname <varname>$hostname</varname> and on failure populate
            <methodname>getMessages()</methodname> with useful error messages.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.hostname.types">
        <title>Validating different types of hostnames</title>

        <para>
            You may find you also want to match IP addresses, Local hostnames, or a combination of
            all allowed types. This can be done by passing a parameter to
            <classname>Zend_Validate_Hostname</classname> when you instantiate it. The parameter
            should be an integer which determines what types of hostnames are allowed. You are
            encouraged to use the <classname>Zend_Validate_Hostname</classname> constants to do
            this.
        </para>

        <para>
            The <classname>Zend_Validate_Hostname</classname> constants are:
            <constant>ALLOW_DNS</constant> to allow only
            <acronym>DNS</acronym> hostnames, <constant>ALLOW_IP</constant> to allow IP addresses,
            <constant>ALLOW_LOCAL</constant> to allow local network names, and
            <constant>ALLOW_ALL</constant> to allow all three above types.
        </para>

        <para>
            Additionally there is <constant>ALLOW_URI</constant> which allows to check hostnames
            according to <ulink url="http://tools.ietf.org/html/rfc3986">RFC3986</ulink>. These
            are registered names which are used by <acronym>WINS</acronym>, NetInfo and also local
            hostnames like those defined within your <filename>.hosts</filename> file. For security
            reasons <constant>ALLOW_URI</constant> is not contained within
            <constant>ALLOW_ALL</constant>.
        </para>

        <para>
            To just check for IP addresses you can use the example below:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_IP);
if ($validator->isValid($hostname)) {
    // hostname appears to be valid
} else {
    // hostname is invalid; print the reasons
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            As well as using <constant>ALLOW_ALL</constant> to accept all common hostnames types
            you can combine these types to allow for combinations. For example, to accept
            <acronym>DNS</acronym> and Local hostnames instantiate your
            <classname>Zend_Validate_Hostname</classname> object as so:
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_DNS |
                                        Zend_Validate_Hostname::ALLOW_IP);
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.hostname.idn">
        <title>Validating International Domains Names</title>

        <para>
            Some Country Code Top Level Domains (ccTLDs), such as 'de' (Germany), support
            international characters in domain names. These are known as International Domain Names
            (<acronym>IDN</acronym>). These domains can be matched by
            <classname>Zend_Validate_Hostname</classname> via extended characters that are used in
            the validation process.
        </para>

        <note>
            <title>IDN domains</title>

            <para>
                Until now more than 50 ccTLDs support <acronym>IDN</acronym> domains.
            </para>
        </note>

        <para>
            To match an <acronym>IDN</acronym> domain it's as simple as just using the standard
            Hostname validator since <acronym>IDN</acronym> matching is enabled by default. If you
            wish to disable <acronym>IDN</acronym> validation this can be done by either passing a
            parameter to the <classname>Zend_Validate_Hostname</classname> constructor or via the
            <methodname>setValidateIdn()</methodname> method.
        </para>

        <para>
            You can disable <acronym>IDN</acronym> validation by passing a second parameter to the
            <classname>Zend_Validate_Hostname</classname> constructor in the following way.
        </para>

        <programlisting language="php"><![CDATA[
$validator =
    new Zend_Validate_Hostname(
        array(
            'allow' => Zend_Validate_Hostname::ALLOW_DNS,
            'idn'   => false
        )
    );
]]></programlisting>

        <para>
            Alternatively you can either pass <constant>TRUE</constant> or
            <constant>FALSE</constant> to <methodname>setValidateIdn()</methodname> to enable or
            disable <acronym>IDN</acronym> validation. If you are trying to match an
            <acronym>IDN</acronym> hostname which isn't currently supported it is likely it will
            fail validation if it has any international characters in it. Where a ccTLD file doesn't
            exist in <filename>Zend/Validate/Hostname</filename> specifying the additional
            characters a normal hostname validation is performed.
        </para>

        <note>
            <title>IDN validation</title>

            <para>
                Please note that <acronym>IDN</acronym>s are only validated if you allow
                <acronym>DNS</acronym> hostnames to be validated.
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.hostname.tld">
        <title>Validating Top Level Domains</title>

        <para>
            By default a hostname will be checked against a list of known <acronym>TLD</acronym>s.
            If this functionality is not required it can be disabled in much the same way as
            disabling <acronym>IDN</acronym> support. You can disable <acronym>TLD</acronym>
            validation by passing a third parameter to the
            <classname>Zend_Validate_Hostname</classname> constructor. In the example below we are
            supporting <acronym>IDN</acronym> validation via the second parameter.
        </para>

        <programlisting language="php"><![CDATA[
$validator =
    new Zend_Validate_Hostname(
        array(
            'allow' => Zend_Validate_Hostname::ALLOW_DNS,
            'idn'   => true,
            'tld'   => false
        )
    );
]]></programlisting>

        <para>
            Alternatively you can either pass <constant>TRUE</constant> or
            <constant>FALSE</constant> to <methodname>setValidateTld()</methodname> to enable or
            disable <acronym>TLD</acronym> validation.
        </para>

        <note>
            <title>TLD validation</title>

            <para>
                Please note <acronym>TLD</acronym>s are only validated if you allow
                <acronym>DNS</acronym> hostnames to be validated.
            </para>
        </note>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->