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

    <para>
        <classname>Zend_Validate_EmailAddress</classname> allows you to validate an email address.
        The validator first splits the email address on local-part @ hostname and attempts to match
        these against known specifications for email addresses and hostnames.
    </para>

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

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

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

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

    <sect3 id="zend.validate.set.email_address.options">
        <title>Options for validating Email Addresses</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> supports several options which can
            either be set at initiation, by giving an array with the related options, or
            afterwards, by using <methodname>setOptions()</methodname>. The following options are
            supported:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis><property>allow</property></emphasis>: Defines which type of domain
                    names are accepted. This option is used in conjunction with the hostname option
                    to set the hostname validator. For more informations about possible values of
                    this option, look at <link linkend="zend.validate.set.hostname">Hostname</link>
                    and possible <constant>ALLOW</constant>* constants. This option defaults to
                    <constant>ALLOW_DNS</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>deep</property></emphasis>: Defines if the servers MX
                    records should be verified by a deep check. When this option is set to
                    <constant>TRUE</constant> then additionally to MX records also the A, A6 and
                    <constant>AAAA</constant> records are used to verify if the server accepts
                    emails. This option defaults to <constant>FALSE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>domain</property></emphasis>: Defines if the domain part
                    should be checked. When this option is set to <constant>FALSE</constant>, then
                    only the local part of the email address will be checked. In this case the
                    hostname validator will not be called. This option defaults to
                    <constant>TRUE</constant>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>hostname</property></emphasis>: Sets the hostname validator
                    with which the domain part of the email address will be validated.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis><property>mx</property></emphasis>: Defines if the MX records from the
                    server should be detected. If this option is defined to
                    <constant>TRUE</constant> then the MX records are used to verify if the server
                    accepts emails. This option defaults to <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>Complex local parts</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> will match any valid email address
            according to RFC2822. For example, valid emails include
            <emphasis>bob@domain.com</emphasis>, <emphasis>bob+jones@domain.us</emphasis>,
            <emphasis>"bob@jones"@domain.com</emphasis> and
            <emphasis>"bob jones"@domain.com</emphasis>.
        </para>

        <para>
            Some obsolete email formats will not currently validate (e.g. carriage returns or a
            "\" character in an email address).
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.purelocal">
        <title>Validating only the local part</title>

        <para>
            If you need <classname>Zend_Validate_EmailAddress</classname> to check only the local
            part of an email address, and want to disable validation of the hostname, you can
            set the <property>domain</property> option to <constant>FALSE</constant>. This forces
            <classname>Zend_Validate_EmailAddress</classname> not to validate the hostname part of
            the email address.
        </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>Validating different types of hostnames</title>

        <para>
            The hostname part of an email address is validated against <link
                linkend="zend.validate.set.hostname">
                <classname>Zend_Validate_Hostname</classname></link>. By default
            only DNS hostnames of the form <filename>domain.com</filename> are accepted, though if
            you wish you can accept IP addresses and Local hostnames too.
        </para>

        <para>
            To do this you need to instantiate <classname>Zend_Validate_EmailAddress</classname>
            passing a parameter to indicate the type of hostnames you want to accept. More details
            are included in <classname>Zend_Validate_Hostname</classname>, though an example of how
            to accept both DNS and Local hostnames appears below:
        </para>

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

    <sect3 id="zend.validate.set.email_address.checkacceptance">
        <title>Checking if the hostname actually accepts email</title>

        <para>
            Just because an email address is in the correct format, it doesn't necessarily mean
            that email address actually exists. To help solve this problem, you can use MX
            validation to check whether an MX (email) entry exists in the DNS record for the
            email's hostname. This tells you that the hostname accepts email, but doesn't tell you
            the exact email address itself is valid.
        </para>

        <para>
            MX checking is not enabled by default. To enable MX checking you can pass a second
            parameter to the <classname>Zend_Validate_EmailAddress</classname> constructor.
        </para>

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

        <note>
            <title>MX Check under Windows</title>

            <para>
                Within Windows environments MX checking is only available when
                <acronym>PHP</acronym> 5.3 or above is used. Below <acronym>PHP</acronym> 5.3 MX
                checking will not be used even if it's activated within the options.
            </para>
        </note>

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

        <para>
            By enabling this setting network functions will be used to check for the presence of an
            MX record on the hostname of the email address you wish to validate. Please be aware
            this will likely slow your script down.
        </para>

        <para>
            Sometimes validation for MX records returns <constant>FALSE</constant>, even if emails
            are accepted. The reason behind this behaviour is, that servers can accept emails even
            if they do not provide a MX record. In this case they can provide A, A6 or
            <constant>AAAA</constant> records. To allow
            <classname>Zend_Validate_EmailAddress</classname> to check also for these other records,
            you need to set deep MX validation. This can be done at initiation by setting the
            <property>deep</property> option or by using <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>Performance warning</title>

            <para>
                You should be aware that enabling MX check will slow down you script because of the
                used network functions. Enabling deep check will slow down your script even more as
                it searches the given server for 3 additional types.
            </para>
        </warning>

        <note>
            <title>Disallowed IP addresses</title>

            <para>
                You should note that MX validation is only accepted for external servers. When deep
                MX validation is enabled, then local IP addresses like <command>192.168.*</command>
                or <command>169.254.*</command> are not accepted.
            </para>
        </note>
    </sect3>

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

        <para>
            <classname>Zend_Validate_EmailAddress</classname> will also match international
            characters that exist in some domains. This is known as International Domain Name (IDN)
            support. This is enabled by default, though you can disable this by changing the
            setting via the internal <classname>Zend_Validate_Hostname</classname> object that
            exists within <classname>Zend_Validate_EmailAddress</classname>.
        </para>

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

        <para>
            More information on the usage of <methodname>setValidateIdn()</methodname> appears in
            the <classname>Zend_Validate_Hostname</classname> documentation.
        </para>

        <para>
            Please note IDNs are only validated if you allow DNS hostnames to be validated.
        </para>
    </sect3>

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

        <para>
            By default a hostname will be checked against a list of known TLDs. This is enabled by
            default, though you can disable this by changing the setting via the internal
            <classname>Zend_Validate_Hostname</classname> object that exists within
            <classname>Zend_Validate_EmailAddress</classname>.
        </para>

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

        <para>
            More information on the usage of <methodname>setValidateTld()</methodname> appears in
            the <classname>Zend_Validate_Hostname</classname> documentation.
        </para>

        <para>
            Please note TLDs are only validated if you allow DNS hostnames to be validated.
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.setmessage">
        <title>Setting messages</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> makes also use of
            <classname>Zend_Validate_Hostname</classname> to check the hostname part of a given
            email address. As with Zend Framework 1.10 you can simply set messages for
            <classname>Zend_Validate_Hostname</classname> from within
            <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>
            Before Zend Framework 1.10 you had to attach the messages to your own
            <classname>Zend_Validate_Hostname</classname>, and then set this validator within
            <classname>Zend_Validate_EmailAddress</classname> to get your own messages returned.
        </para>
    </sect3>
</sect2>
<!--
vim:se ts=4 sw=4 et:
-->