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

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

    <title>Dirección de Email</title>

    <para>
        <classname>Zend_Validate_EmailAddress</classname> Le permite validar una
        dirección de email. El validador primero divide la dirección de email en
        la parte local @ nombre de host e intenta igualar a estos contra
        especificaciones conocidas para direcciones y nombres de host para el
        correo electrónico. </para>

    <sect3 id="zend.validate.set.email_address.basic">
        <title>Utilización básica</title>

        <para> Un ejemplo básico de uso se ve a continuación: </para>

        <programlisting language="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();
if ($validator->isValid($email)) {
    // El email parece ser válido
} else {
    // El email es inválido; muestre las razones
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

        <para> Esto coincide con el correo electrónico <varname>$email</varname>
            y si fracasa, alimenta <code>$validator->getMessages()</code> con
            mensajes de error útiles. </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.options">

        <title>>Partes locales complejas</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>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>

            <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>
        </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> se comparará con
            cualquier dirección de correo válida de acuardo a RFC2822. Por
            ejemplo, correos electrónicos válidos incluyen
                <code>bob@domain.com</code> , <code>bob+jones@domain.us</code> ,
                <code>"bob@jones"@domain.com</code> y <code>"bob
                jones"@domain.com</code>
        </para>

        <para> Algunos formatos obsoletos de email actualmente no validan (por
            ejemplo los retornos de carro o "\" un caracter en una dirección de
            correo electrónico). </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> La parte nombre de host de una dirección de correo es validado
            contra <link linkend="zend.validate.set.hostname">
                <classname>Zend_Validate_Hostname</classname>
            </link> . Por defecto sólo son aceptados nombres de host DNS de la
            forma <methodname>domain.com</methodname> , aunque si lo desea
            también puede aceptar direcciones IP y nombres de host locales. </para>

        <para> Para ello necesita instanciar a
                <classname>Zend_Validate_EmailAddress</classname> pasando un
            parámetro para indicar el tipo de nombres de host que quiere
            aceptar. Más detalles están incluidos en
                <classname>Zend_Validate_EmailAddress</classname> , aunque abajo
            hay un ejemplo de cómo aceptar tanto nombres de host DNS y locales: </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 parece ser válido
} else {
    // email es inválido; muestre las razones
    foreach ($validator->getMessages() as $message) {
        echo "$message\n";
    }
}
]]></programlisting>

    </sect3>
    <sect3 id="zend.validate.set.email_address.checkacceptance">

        <title>Verificar si el nombre de host realmente acepta email</title>

        <para> Sólo porque una dirección de correo electrónico está en el
            formato correcto, no necesariamente significa que esa dirección de
            correo electrónico existe realmente. Para ayudar a resolver este
            problema, puede usar la validación MX para comprobar si existe una
            entrada MX (email) en el registro DNS para correo electrónico en ese
            nombre de host. Esto le dice que el nombre de host acepta email,
            pero no le dice si la dirección de correo electrónico exacta es
            válida en si misma. </para>

        <para> La comprobación MX no está activada por defecto y en este momento
            es soportada sólo por plataformas UNIX. Para habilitar el control MX
            puede pasar un segundo parámetro al constructor
                <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> Alternativamente, para activar o desactivar la validación MX
            puede pasar <constant>TRUE</constant> o <constant>FALSE</constant> a
                <methodname>$validator->setValidateMx()</methodname> . </para>

        <para> Al habilitarlo, se usarán las funciones de red para comprobar la
            presencia de un registro MX en el nombre de host de la dirección de
            correo electrónico que desea validar. Tenga en cuenta esto
            probablemente hará más lento su script. </para>

        <para> Sometimes validation for MX records returns false, 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> también comparará
            caracteres internationales que existen en algunos dominios. Esto se
            conoce como soporte de International Domain Name (IDN). Está
            activado por defecto, aunque puede deshabilitarlo internamente
            cambiando el ajuste a través del objeto
                <classname>Zend_Validate_Hostname</classname> que existe en
                <classname>Zend_Validate_EmailAddress</classname> . </para>

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

        <para> Sobre el uso de <methodname>setValidateIdn()</methodname>
            encontrará más información en la documentación de
                <classname>Zend_Validate_Hostname</classname> . </para>

        <para> Tenga en cuenta que los IDNs se validarán solo si usted permite
            que nombres de host DNS sean validados. </para>
    </sect3>

    <sect3 id="zend.validate.set.email_address.validatetld">
        <title>Validación de dominios de nivel superior</title>

        <para> Por defecto, un nombre de host se cotejará con una lista conocida
            de TLDs. Está activado por defecto, aunque puede deshabilitarlo
            cambiando el ajuste a través del objeto interno
                <classname>Zend_Validate_Hostname</classname> que existe en
                <classname>Zend_Validate_EmailAddress</classname> . </para>

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

        <para> Encontrará más información sobre el uso de
                <methodname>setValidateTld()</methodname> en la documentación de
                <classname>Zend_Validate_Hostname</classname> . </para>

        <para> Tenga en cuenta que los TLDs se validarán solo si usted permite
            que nombres de host DNS sean validados. </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>