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

<?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>

    <para>
        <emphasis role="strong">Basic usage</emphasis>
    </para>

    <para>
        A basic example of usage is below:

        <programlisting role="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>

        This will match the email address <code>$email</code> and on failure populate
        <code>$validator->getMessages()</code> with useful error messages.
    </para>

    <para>
        <emphasis role="strong">Complex local parts</emphasis>
    </para>

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

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

    <para>
        <emphasis role="strong">Validating different types of hostnames</emphasis>
    </para>

    <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 <code>domain.com</code> 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:

        <programlisting role="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>
    </para>

    <para>
        <emphasis role="strong">Checking if the hostname actually accepts email</emphasis>
    </para>

    <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 and at this time is only supported by UNIX platforms.
        To enable MX checking you can pass a second parameter to the <classname>Zend_Validate_EmailAddress</classname>
        constructor.

        <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(Zend_Validate_Hostname::ALLOW_DNS,
                                            true);
]]></programlisting>

        Alternatively you can either pass <code>true</code> or <code>false</code> to
        <code>$validator->setValidateMx()</code> 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>
        <emphasis role="strong">Validating International Domains Names</emphasis>
    </para>

    <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>.

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

        More information on the usage of <code>setValidateIdn()</code> 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>

    <para>
        <emphasis role="strong">Validating Top Level Domains</emphasis>
    </para>

    <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>.

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

        More information on the usage of <code>setValidateTld()</code> 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>

</sect2>
<!--
vim:se ts=4 sw=4 et:
-->