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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 21247 -->
<sect2 id="zend.validate.set.hostname">

    <title>ホスト名</title>

    <para>
        <classname>Zend_Validate_Hostname</classname> は、ホスト名が仕様を満たしているかどうかの検証を行います。
        三種類の形式のホスト名、つまり <acronym>DNS</acronym> ホスト名
        (たとえば domain.com)、IP アドレス (たとえば 1.2.3.4)
        そしてローカルホスト名 (たとえば localhost) の検証が可能です。
        デフォルトでは <acronym>DNS</acronym> ホスト名のみが有効となります。
    </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>基本的な使用法</title>

        <para>
           基本的な使用法は、以下のようになります。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Hostname();
if ($validator->isValid($hostname)) {
    // ホスト名は正しい形式のようです
} else {
    // 不正な形式なので、理由を表示します
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            これは、ホスト名 <varname>$hostname</varname> を検証し、失敗した場合は
            その原因を表す便利なエラーメッセージを
            <methodname>$validator->getMessages()</methodname> で取得します。
        </para>

    </sect3>

    <sect3 id="zend.validate.set.hostname.types">
        <title>さまざまな形式のホスト名を検証</title>

        <para>
            IP アドレスやローカルホスト名、あるいはその両方を正しいホスト名として認めたいこともあるでしょう。
            その場合は、<classname>Zend_Validate_Hostname</classname> のインスタンスを作成する際にパラメータを渡します。
            このパラメータには、どの形式のホスト名を許可するのかを表す整数値を指定しなければなりません。
            できるだけ、<classname>Zend_Validate_Hostname</classname> の定数を使用するようにしましょう。
        </para>

        <para>
            <classname>Zend_Validate_Hostname</classname> の定数は次のとおりです。<constant>ALLOW_DNS</constant> は <acronym>DNS</acronym> ホスト名のみを許可し、
            <constant>ALLOW_IP</constant> は IP アドレスを許可します。また <constant>ALLOW_LOCAL</constant>
            はローカルネットワーク名を許可し、<constant>ALLOW_ALL</constant> はこれら三種類をすべて許可します。
            IP アドレスだけをチェックするには、以下の例のようにします。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_Hostname(Zend_Validate_Hostname::ALLOW_IP);
if ($validator->isValid($hostname)) {
    // ホスト名は正しい形式のようです
} else {
    // 不正な形式なので、理由を表示します
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            <constant>ALLOW_ALL</constant> を使用してすべての形式を許可するほかに、
            これらの形式を組み合わせることもできます。
            たとえば、 <acronym>DNS</acronym> およびローカルホスト名を許可するには、
            <classname>Zend_Validate_Hostname</classname> のインスタンスを次のように作成します。
        </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>国際化ドメイン名を検証</title>

        <para>
            国別コードトップレベルドメイン (Country Code Top Level Domains: ccTLDs)
            の一部、たとえば 'de' (ドイツ) などでは、ドメイン名の中に国際化文字の使用をサポートしています。
            これは、国際化ドメイン名 (International Domain Names: <acronym>IDN</acronym>) といわれるものです。
            これらのドメインについても、<classname>Zend_Validate_Hostname</classname>
            の検証プロセスで使用する文字を拡張することで検証できます。
        </para>

        <note>
            <title>IDN ドメイン</title>

            <para>
                これまでに、50以上の ccTLD が <acronym>IDN</acronym> ドメインをサポートします。
            </para>
        </note>

        <para>
            <acronym>IDN</acronym> ドメインに対するマッチングを行う方法は、通常のホスト名の場合とまったく同じです。
            というのも、 <acronym>IDN</acronym> のマッチングはデフォルトで有効になっているからです。
            <acronym>IDN</acronym> の検証を無効にしたい場合は、<classname>Zend_Validate_Hostname</classname>
            のコンストラクタにパラメータを渡すか、あるいは
            <methodname>setValidateIdn()</methodname> メソッドを使用します。
        </para>

        <para>
            <acronym>IDN</acronym> の検証を無効にするには、<classname>Zend_Validate_Hostname</classname>
            のコンストラクタに二番目のパラメータを次のように渡します。
        </para>

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

        <para>
            あるいは、 <constant>TRUE</constant> または <constant>FALSE</constant> を
            <methodname>setValidateIdn()</methodname> に渡すことで、
            <acronym>IDN</acronym> の検証を有効あるいは無効にすることもできます。
            現在サポートされていない <acronym>IDN</acronym> ホスト名に対するマッチングを行おうとすると、
            国際化文字が含まれている場合に検証に失敗します。
            追加の文字を指定した ccTLD ファイルが <filename>Zend/Validate/Hostname</filename>
            に存在しない場合は、通常のホスト名の検証を行います。
        </para>

        <note>
            <title>IDN 検証</title>

            <para>
                <acronym>IDN</acronym> の検証は、 <acronym>DNS</acronym> ホスト名の検証を有効にしている場合にのみ行われることに注意しましょう。
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.hostname.tld">
        <title>トップレベルドメインを検証</title>

        <para>
            デフォルトでは、ホスト名の検証は既知の <acronym>TLD</acronym> の一覧に基づいて行われます。
            この機能が不要な場合は、 <acronym>IDN</acronym> サポートを無効にするのと同じ方法で無効にできます。
            <acronym>TLD</acronym> の検証を無効にするには、<classname>Zend_Validate_Hostname</classname> のコンストラクタに三番目のパラメータを渡します。
            以下の例では、 <acronym>IDN</acronym> の検証は二番目のパラメータで有効にしています。
        </para>

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

        <para>
            あるいは、 <constant>TRUE</constant> または <constant>FALSE</constant> を
            <methodname>setValidateIdn()</methodname> に渡すことで、
            <acronym>TLD</acronym> の検証を有効あるいは無効にすることもできます。
        </para>

        <note>
            <title>TLD 検証</title>

            <para>
                <acronym>TLD</acronym> の検証は、 <acronym>DNS</acronym> ホスト名の検証を有効にしている場合にのみ行われることに注意しましょう。
            </para>
        </note>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->