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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect2 id="zend.validate.set.email_address">
    <title>メールアドレス</title>

    <para>
        <classname>Zend_Validate_EmailAddress</classname> は、メールアドレスの検証を行います。
        このバリデータは、まずメールアドレスを
        local-part @ hostname
        に分割し、メールアドレスやホスト名の仕様にあわせて検証します。
    </para>

    <sect3 id="zend.validate.set.email_address.basic">
        <title>基本的な使用法</title>

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

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

        <para>
            これは、メールアドレス <varname>$email</varname> を検証し、失敗した場合は
            その原因を表す便利なエラーメッセージを
            <methodname>getMessages()</methodname> で取得します。
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.options">
        <title>メールアドレス検証のオプション</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname>は、
            開始時に関係するオプションを持つ配列を与えることによって、
            または後で <methodname>setOptions()</methodname> を使って
            セットできるいくつかのオプションをサポートします。
            下記のオプションがサポートされます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>allow</property></emphasis>: ドメイン名のいずれのタイプを受付可能か定義します。
                    このオプションは、ホスト名バリデータをセットするために
                    hostname オプションとともに使われます。
                    このオプションで可能な値について詳しくは、
                    <link linkend="zend.validate.set.hostname">ホスト名</link>をご覧ください。
                    そして <constant>ALLOW</constant>* 定数が可能です。
                    既定値は <constant>ALLOW_DNS</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>deep</property></emphasis>: サーバの MX レコードを強度のチェックで検証するべきかどうか定義します。
                    このオプションが <constant>TRUE</constant> に設定されると、
                    サーバがメールを受け付けるかどうか検証するために、
                    MX レコードに加えて A , A6 及び <constant>AAAA</constant> レコードも使われます。
                    このオプションの既定値は <constant>FALSE</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>domain</property></emphasis>: ドメインパートをチェックすべきかどうか定義します。
                    このオプションが <constant>FALSE</constant> に設定されると、
                    メールアドレスのローカルパートのみがチェックされます。
                    この場合、ホスト名バリデータは呼ばれません。
                    このオプションの既定値は <constant>TRUE</constant> です。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>hostname</property></emphasis>: 検証される電子メール・アドレスのドメインパートで
                    ホスト名バリデータをセットします。
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>mx</property></emphasis>: サーバから MX レコードが検出されるべきかどうか定義します。
                    もしこのオプションが <constant>TRUE</constant> と定義されると、
                    サーバがメールを受け付けるかどうか検証するために MX レコードが使われます。
                    このオプションの既定値は <constant>FALSE</constant> です。
                </para>
            </listitem>
        </itemizedlist>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => false));
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.complexlocal">
        <title>複雑なローカルパート</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> は、メールアドレスの検証を
            RFC2822 にもとづいて行います。たとえば、妥当な形式のメールアドレスとしては
            <emphasis>bob@domain.com</emphasis>、<emphasis>bob+jones@domain.us</emphasis>、
            <emphasis>"bob@jones"@domain.com</emphasis> および <emphasis>"bob jones"@domain.com</emphasis>
            などがあります。
        </para>

        <para>
            かつて使われていたものの、現在は有効とはみなされないフォーマットもあります
            (たとえば、メールアドレスに改行文字や "\" を使用するなど)。
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.purelocal">
        <title>ローカルパートのみの検証</title>

        <para>
            もしメールアドレスのローカルパートのみをチェックするために
            <classname>Zend_Validate_EmailAddress</classname> を必要として、
            ホスト名の検証を無効にしたいなら、
            <property>domain</property> オプションに <constant>FALSE</constant> を設定できます。
            これにより、 <classname>Zend_Validate_EmailAddress</classname> が
            メールアドレスのホスト名部分を検証しないようにします。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => FALSE));
]]></programlisting>
    </sect3>

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

        <para>
            メールアドレスのホスト名部分の検証は、
            <link linkend="zend.validate.set.hostname"><classname>Zend_Validate_Hostname</classname></link>
            で行います。デフォルトでは、<filename>domain.com</filename>
            形式の DNS ホスト名のみが有効となります。しかし、
            IP アドレスやローカルホスト名も有効にしたいこともあるでしょう。
        </para>

        <para>
            その場合は、<classname>Zend_Validate_EmailAddress</classname>
            のインスタンスを作成する際にパラメータを渡さなければなりません。
            このパラメータで、認めたいホスト名の形式を指定します。
            詳細は <classname>Zend_Validate_Hostname</classname> を参照ください。
            たとえば DNS ホスト名およびローカルホスト名のどちらも許可するには、次のようにします。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(
                    Zend_Validate_Hostname::ALLOW_DNS |
                    Zend_Validate_Hostname::ALLOW_LOCAL);
if ($validator->isValid($email)) {
    // メールアドレスは正しい形式のようです
} else {
    // 不正な形式なので、理由を表示します
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.checkacceptance">
        <title>そのホスト名が実際にメールを受け付けるかどうかのチェック</title>

        <para>
            ただ単にメールアドレスが正しい書式であるというだけでは、
            そのアドレスが実際に存在するかどうかはわかりません。
            この問題を解決するには、MX の検証を行います。
            メールアドレスのホスト名に対応する DNS レコードに、MX (メール)
            のエントリが存在するかどうかを調べるのです。
            これは、そのホストがメールを受け付けているかどうかを教えてはくれますが、
            そのメールアドレス自体が正しいものであるかどうかを知ることはできません。
        </para>

        <para>
            MX のチェックはデフォルトでは無効です。
            MX のチェックを有効にするには、<classname>Zend_Validate_EmailAddress</classname>
            コンストラクタの 2 番目のパラメータを渡します。
        </para>

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

        <note>
            <title>WindowsでのMX のチェック</title>

            <para>
                Windows 環境の範囲内では、
                MX のチェックは <acronym>PHP</acronym> 5.3 かそれ以上を使う場合のみ可能です。
                <acronym>PHP</acronym> 5.3 未満では MX のチェックはオプションで有効にされたとしても、
                使われません。
            </para>
        </note>

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

        <para>
            この設定を有効にすると、ネットワーク関数を用いて
            メールアドレスのホスト名部に対する MX レコードの存在チェックをします。
            これにより、スクリプトの処理速度が低下することに気をつけてください。
        </para>

        <para>
            しばしば MX レコードの検証は、メールが受け付けられたとしても <constant>FALSE</constant> を返します。
            この振る舞いの背後にある理由は、サーバが MX レコードを提供しなくてもサーバはメールを受付できることです。
            この場合、サーバは A, A6 または <constant>AAAA</constant> レコードを提供します。
            それらのほかのレコードでも <classname>Zend_Validate_EmailAddress</classname> がチェックできるようにするためには、
            強度の MX 検証を設定する必要があります。
            これは開始時に <property>deep</property> オプションを設定するか、
            または <methodname>setOptions()</methodname> を使って行ないます。
        </para>

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

        <warning>
            <title>パフォーマンスの警告</title>

            <para>
                MX チェックを有効にすると、使用されるネットワーク機能のせいで
                スクリプトが遅くなることに気づくでしょう。
                強度のチェックを有効にすると与えられたサーバで追加の３種類を探すため、
                さらにスクリプトが遅くなります。
            </para>
        </warning>

        <note>
            <title>許可されないIPアドレス</title>

            <para>
                MX 検証は外部のサーバでのみ受け付けられることを注意すべきです。
                強度の MX 検証が有効なとき、
                <command>192.168.*</command> や <command>169.254.*</command> のような
                ローカル IP アドレスは受け付けません。
            </para>
        </note>
    </sect3>

    <sect3 id="zend.validate.set.email_address.validateidn">
        <title>国際化ドメイン名の検証</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> は、ドメインの中に国際文字が使われている場合も処理できます。
            このようなドメインは、国際化ドメイン名 (International Domain Name: IDN)
            と呼ばれています。これはデフォルトで有効になっていますが、無効にすることも可能です。
            無効にするには、<classname>Zend_Validate_EmailAddress</classname> が内部で保持している
            <classname>Zend_Validate_Hostname</classname> オブジェクトの設定を変更します。
        </para>

        <programlisting language="php"><![CDATA[
$validator->getHostnameValidator()->setValidateIdn(false);
]]></programlisting>

        <para>
            <methodname>setValidateIdn()</methodname> の詳細な使用法は、
            <classname>Zend_Validate_Hostname</classname> のドキュメントを参照ください。
        </para>

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

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

        <para>
            デフォルトでは、ホスト名の検証は既知の TLD の一覧に基づいて行われます。
            これはデフォルトで有効になっていますが、無効にすることもできます。無効にするには、
            無効にするには、<classname>Zend_Validate_EmailAddress</classname> が内部で保持している
            <classname>Zend_Validate_Hostname</classname> オブジェクトの設定を変更します。
        </para>

        <programlisting language="php"><![CDATA[
$validator->getHostnameValidator()->setValidateTld(false);
]]></programlisting>

        <para>
            <methodname>setValidateTld()</methodname> の詳細な使用法は、
            <classname>Zend_Validate_Hostname</classname> のドキュメントを参照ください。
        </para>

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

    <sect3 id="zend.validate.set.email_address.setmessage">
        <title>メッセージの設定</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> は、
            <classname>Zend_Validate_Hostname</classname> を使用してメールアドレスのホスト名部分をチェックします。
            Zend Framework 1.10 以降、
            <classname>Zend_Validate_Hostname</classname> 用のメッセージを
            <classname>Zend_Validate_EmailAddress</classname>
            から設定できるようになります。
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
$validator->setMessages(
    array(
        Zend_Validate_Hostname::UNKNOWN_TLD => "I don't know the TLD you gave"
    )
);
]]></programlisting>

        <para>
            Zend Framework 1.10 より前のバージョンでは、まず
            <classname>Zend_Validate_Hostname</classname> にメッセージをアタッチしてからそれを
            <classname>Zend_Validate_EmailAddress</classname> に設定しないと独自のメッセージを返せませんでした。
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->