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

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

    <para>
        <classname>Zend_Validate_EmailAddress</classname> permet de valider une adresse mail.
        Ce validateur éclate d'abord l'adresse mail entre partie locale et domaine et essaie de
        valider ces deux parties conformément aux spécifications des adresses mail et des noms de
        domaine.
    </para>

    <sect3 id="zend.validate.set.email_address.basic">
        <title>Utilisation de base</title>

        <para>Vous trouverez ci-dessous un exemple d'utilisation basique&#160;</para>

        <programlisting language="php"><![CDATA[
$validateur = new Zend_Validate_EmailAddress();
if ($validateur->isValid($email)) {
    // l'email est valide
} else {
    // l'email est invalide ; afficher pourquoi
    foreach ($validateur->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para>
            Ceci validera l'adresse mail <varname>$email</varname> et, en cas d'échec,
            fournira des messages d'erreur informatifs via
            <code>$validator-&gt;getMessages()</code>.
        </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>allow</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>deep</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>domain</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>hostname</emphasis>: Sets the hostname validator with which the
                    domain part of the email address will be validated.
                </para>
            </listitem>

            <listitem>
                <para>
                    <emphasis>mx</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>Parties locales complexes</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> validera toute adresse mail
            conforme à la RFC2822. Comme par exemple <code>bob@domaine.com</code>,
            <code>bob+jones@domaine.fr</code>, <code>"bob@jones"@domaine.com</code> et <code>"bob
            jones"@domaine.com</code>. Quelques formats de mail obsolètes ne seront pas validés (comme
            toute adresse mail contenant un retour chariot ou un caractère "\").
        </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.purelocal">
        <title>Validation uniquement de la partie locale</title>

        <para>
            Si vous avez besoin de <classname>Zend_Validate_EmailAddress</classname> uniquement pour
            vérifier la partie locale d'une adresse mail, et que vous souhaitez désactiver la
            validation du nom d'hôte, vous pouvez spécifier le paramètre <property>domain</property>
            à la valeur <constant>false</constant>. Cela force <classname>Zend_Validate_EmailAddress
            </classname> à ne pas valider le nom d'hôte de l'adresse mail.
        </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>Validation de différents types de noms de domaine</title>

        <para>
            La partie domaine d'une adresse mail est validée via <link
            linkend="zend.validate.set.hostname"><classname>Zend_Validate_Hostname</classname></link>.
            Par défaut, seules les domaines qualifiés sous la forme <code>domaine.com</code> sont
            acceptés, même si, il vous est possible d'accepter les adresses IP et les domaines locaux
            également.
        </para>

        <para>
            Afin de réaliser cette opération, il vous faut instancier
            <classname>Zend_Validate_EmailAddress</classname> en lui passant un paramètre indiquant le
            type de nom de domaine à accepter. Les détails sont disponibles dans
            <classname>Zend_Validate_EmailAddress</classname> mais vous trouverez ci-dessous un exemple
            illustrant comment accepter les noms de domaines qualifiés et les hôtes locaux :
        </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress(
                    Zend_Validate_Hostname::ALLOW_DNS |
                    Zend_Validate_Hostname::ALLOW_LOCAL);
if ($validator->isValid($email)) {
    // l'email est valide
} else {
    // l'email est invalide ; afficher pourquoi
    foreach ($validateur->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>
    </sect3>

    <sect3 id="zend.validate.set.email_address.checkacceptance">
        <title>Vérification que le nom de domaine accepte réellement le courriel</title>

        <para>
            Le fait qu'une adresse électronique est dans un format correct, ne signifie pas
            nécessairement que l'adresse électronique existe en réalité. Pour aider résoudre ce
            problème, vous pouvez utiliser la validation MX pour vérifier si une entrée MX (le courriel)
            existe dans le l'enregistrement du DNS pour le nom de domaine du courriel. Cela vous dit que
            le nom de domaine accepte le courriel, mais ne vous dit pas que l'adresse électronique elle-même
            est valable.
        </para>

        <para>
            La vérification MX n'est pas active par défaut et est seulement supporté par des
            plates-formes UNIX pour l'instant. Pour activer la vérification MX vous pouvez passer un
            deuxième paramètre au constructeur <classname>Zend_Validate_EmailAddress</classname>.
        </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>
            Alternativement vous pouvez passer soit <constant>TRUE</constant> soit
            <constant>FALSE</constant> à <code>$validator-&gt;setValidateMx()</code> pour activer ou désactiver
            la validation MX.
        </para>

        <para>
            En activant ce paramètre, les fonctions de réseau seront utilisés pour vérifier la
            présence d'un enregistrement MX sur le nom de domaine de l'adresse électronique que vous
            voulez valider. Faîtes cependant attention, cela ralentira probablement votre
            scénario.
        </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>Valider les noms de domaines internationaux</title>

        <para>
            <classname>Zend_Validate_EmailAddress</classname> peut aussi vérifier les caractères
            internationaux qui existent dans quelques domaines. Ceci est connu comme le support de Nom
            de Domaine International (IDN). Celui-ci est activé par défaut, quoique vous puissiez le
            mettre hors service en changeant le paramètre via l'objet interne
            <classname>Zend_Validate_Hostname</classname> qui existe dans
            <classname>Zend_Validate_EmailAddress</classname>.
        </para>

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

        <para>
            De plus amples informations concernant l'utilisation de
            <methodname>setValidateIdn()</methodname> sont présentes dans la <link
            linkend="zend.validate.set.hostname">documentation de
            <classname>Zend_Validate_Hostname</classname></link>.
        </para>

        <para>
            Notez cependant que les IDNs sont seulement validés si vous autorisez la validation
            des nom de domaines.
        </para>
    </sect3>

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

        <para>
            Par défaut un nom de domaine sera vérifié grâce à une liste de TLDs connus. Ceci est
            activé par défaut, quoique vous puissiez le mettre hors service en changeant le paramètre
            via l'objet <classname>Zend_Validate_Hostname</classname> interne qui existe dans
            <classname>Zend_Validate_EmailAddress</classname>.
        </para>

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

        <para>
            De plus amples informations concernant l'utilisation de
            <methodname>setValidateTld()</methodname> sont présentes dans la <link
            linkend="zend.validate.set.hostname">documentation de
            <classname>Zend_Validate_Hostname</classname></link>.
        </para>

        <para>
            Notez cependant que les TLDs sont seulement validés si vous autorisez la validation
            des nom de domaines.
        </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>