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

<?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 19419 -->
    <!-- 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 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>

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