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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 21241 -->
   3     <!-- Reviewed: no -->
   4 <sect2 id="zend.validate.set.email_address">
   5
   6     <title>Dirección de Email</title>
   7
   8     <para>
   9         <classname>Zend_Validate_EmailAddress</classname> Le permite validar una
  10         dirección de email. El validador primero divide la dirección de email en
  11         la parte local @ nombre de host e intenta igualar a estos contra
  12         especificaciones conocidas para direcciones y nombres de host para el
  13         correo electrónico. </para>
  14
  15     <sect3 id="zend.validate.set.email_address.basic">
  16         <title>Utilización básica</title>
  17
  18         <para> Un ejemplo básico de uso se ve a continuación: </para>
  19
  20         <programlisting language="php"><![CDATA[
  21 $validator = new Zend_Validate_EmailAddress();
  22 if ($validator->isValid($email)) {
  23     // El email parece ser válido
  24 } else {
  25     // El email es inválido; muestre las razones
  26     foreach ($validator->getMessages() as $message) {
  27         echo "$message\n";
  28     }
  29 }
  30 ]]></programlisting>
  31
  32         <para> Esto coincide con el correo electrónico <varname>$email</varname>
  33             y si fracasa, alimenta <code>$validator->getMessages()</code> con
  34             mensajes de error útiles. </para>
  35     </sect3>
  36
  37     <sect3 id="zend.validate.set.email_address.options">
  38
  39         <title>>Partes locales complejas</title>
  40
  41         <para>
  42             <classname>Zend_Validate_EmailAddress</classname> supports several
  43             options which can either be set at initiation, by giving an array
  44             with the related options, or afterwards, by using
  45                 <methodname>setOptions()</methodname> . The following options
  46             are supported: </para>
  47
  48         <itemizedlist>
  49             <listitem>
  50                 <para>
  51                     <emphasis>allow</emphasis> : Defines which type of domain
  52                     names are accepted. This option is used in conjunction with
  53                     the hostname option to set the hostname validator. For more
  54                     informations about possible values of this option, look at
  55                         <link linkend="zend.validate.set.hostname"
  56                         >Hostname</link> and possible <constant>ALLOW</constant>
  57                     * constants. This option defaults to
  58                         <constant>ALLOW_DNS</constant> . </para>
  59             </listitem>
  60
  61             <listitem>
  62                 <para>
  63                     <emphasis>hostname</emphasis> : Sets the hostname validator
  64                     with which the domain part of the email address will be
  65                     validated. </para>
  66             </listitem>
  67
  68             <listitem>
  69                 <para>
  70                     <emphasis>mx</emphasis> : Defines if the MX records from the
  71                     server should be detected. If this option is defined to
  72                         <constant>TRUE</constant> then the MX records are used
  73                     to verify if the server accepts emails. This option defaults
  74                     to <constant>FALSE</constant> . </para>
  75             </listitem>
  76
  77             <listitem>
  78                 <para>
  79                     <emphasis>deep</emphasis> : Defines if the servers MX
  80                     records should be verified by a deep check. When this option
  81                     is set to <constant>TRUE</constant> then additionally to MX
  82                     records also the A, A6 and <constant>AAAA</constant> records
  83                     are used to verify if the server accepts emails. This option
  84                     defaults to <constant>FALSE</constant> . </para>
  85             </listitem>
  86
  87             <listitem>
  88                 <para>
  89                     <emphasis>domain</emphasis> : Defines if the domain part
  90                     should be checked. When this option is set to
  91                         <constant>FALSE</constant> , then only the local part of
  92                     the email address will be checked. In this case the hostname
  93                     validator will not be called. This option defaults to
  94                         <constant>TRUE</constant> . </para>
  95             </listitem>
  96         </itemizedlist>
  97
  98         <programlisting language="php"><![CDATA[
  99 $validator = new Zend_Validate_EmailAddress();
 100 $validator->setOptions(array('domain' => false));
 101 ]]></programlisting>
 102     </sect3>
 103
 104     <sect3 id="zend.validate.set.email_address.complexlocal">
 105         <title>Complex local parts</title>
 106
 107         <para>
 108             <classname>Zend_Validate_EmailAddress</classname> se comparará con
 109             cualquier dirección de correo válida de acuardo a RFC2822. Por
 110             ejemplo, correos electrónicos válidos incluyen
 111                 <code>bob@domain.com</code> , <code>bob+jones@domain.us</code> ,
 112                 <code>"bob@jones"@domain.com</code> y <code>"bob
 113                 jones"@domain.com</code>
 114         </para>
 115
 116         <para> Algunos formatos obsoletos de email actualmente no validan (por
 117             ejemplo los retornos de carro o "\" un caracter en una dirección de
 118             correo electrónico). </para>
 119
 120     </sect3>
 121
 122     <sect3 id="zend.validate.set.email_address.purelocal">
 123         <title>Validating only the local part</title>
 124
 125         <para> If you need <classname>Zend_Validate_EmailAddress</classname> to
 126             check only the local part of an email address, and want to disable
 127             validation of the hostname, you can set the
 128                 <property>domain</property> option to <constant>FALSE</constant>
 129             . This forces <classname>Zend_Validate_EmailAddress</classname> not
 130             to validate the hostname part of the email address. </para>
 131
 132         <programlisting language="php"><![CDATA[
 133 $validator = new Zend_Validate_EmailAddress();
 134 $validator->setOptions(array('domain' => FALSE));
 135 ]]></programlisting>
 136     </sect3>
 137
 138     <sect3 id="zend.validate.set.email_address.hostnametype">
 139         <title>Validating different types of hostnames</title>
 140
 141         <para> La parte nombre de host de una dirección de correo es validado
 142             contra <link linkend="zend.validate.set.hostname">
 143                 <classname>Zend_Validate_Hostname</classname>
 144             </link> . Por defecto sólo son aceptados nombres de host DNS de la
 145             forma <methodname>domain.com</methodname> , aunque si lo desea
 146             también puede aceptar direcciones IP y nombres de host locales. </para>
 147
 148         <para> Para ello necesita instanciar a
 149                 <classname>Zend_Validate_EmailAddress</classname> pasando un
 150             parámetro para indicar el tipo de nombres de host que quiere
 151             aceptar. Más detalles están incluidos en
 152                 <classname>Zend_Validate_EmailAddress</classname> , aunque abajo
 153             hay un ejemplo de cómo aceptar tanto nombres de host DNS y locales: </para>
 154
 155         <programlisting language="php"><![CDATA[
 156 $validator = new Zend_Validate_EmailAddress(
 157                     Zend_Validate_Hostname::ALLOW_DNS |
 158                     Zend_Validate_Hostname::ALLOW_LOCAL);
 159 if ($validator->isValid($email)) {
 160     // email parece ser válido
 161 } else {
 162     // email es inválido; muestre las razones
 163     foreach ($validator->getMessages() as $message) {
 164         echo "$message\n";
 165     }
 166 }
 167 ]]></programlisting>
 168
 169     </sect3>
 170     <sect3 id="zend.validate.set.email_address.checkacceptance">
 171
 172         <title>Verificar si el nombre de host realmente acepta email</title>
 173
 174         <para> Sólo porque una dirección de correo electrónico está en el
 175             formato correcto, no necesariamente significa que esa dirección de
 176             correo electrónico existe realmente. Para ayudar a resolver este
 177             problema, puede usar la validación MX para comprobar si existe una
 178             entrada MX (email) en el registro DNS para correo electrónico en ese
 179             nombre de host. Esto le dice que el nombre de host acepta email,
 180             pero no le dice si la dirección de correo electrónico exacta es
 181             válida en si misma. </para>
 182
 183         <para> La comprobación MX no está activada por defecto y en este momento
 184             es soportada sólo por plataformas UNIX. Para habilitar el control MX
 185             puede pasar un segundo parámetro al constructor
 186                 <classname>Zend_Validate_EmailAddress</classname> . </para>
 187
 188         <programlisting language="php"><![CDATA[
 189 $validator = new Zend_Validate_EmailAddress(
 190     array(
 191         'allow' => Zend_Validate_Hostname::ALLOW_DNS,
 192         'mx'    => true
 193     )
 194 );
 195 ]]></programlisting>
 196
 197         <note>
 198             <title>MX Check under Windows</title>
 199
 200             <para> Within Windows environments MX checking is only available
 201                 when <acronym>PHP</acronym> 5.3 or above is used. Below
 202                     <acronym>PHP</acronym> 5.3 MX checking will not be used even
 203                 if it's activated within the options. </para>
 204         </note>
 205
 206         <para> Alternativamente, para activar o desactivar la validación MX
 207             puede pasar <constant>TRUE</constant> o <constant>FALSE</constant> a
 208                 <methodname>$validator->setValidateMx()</methodname> . </para>
 209
 210         <para> Al habilitarlo, se usarán las funciones de red para comprobar la
 211             presencia de un registro MX en el nombre de host de la dirección de
 212             correo electrónico que desea validar. Tenga en cuenta esto
 213             probablemente hará más lento su script. </para>
 214
 215         <para> Sometimes validation for MX records returns false, even if emails
 216             are accepted. The reason behind this behaviour is, that servers can
 217             accept emails even if they do not provide a MX record. In this case
 218             they can provide A, A6 or <constant>AAAA</constant> records. To
 219             allow <classname>Zend_Validate_EmailAddress</classname> to check
 220             also for these other records, you need to set deep MX validation.
 221             This can be done at initiation by setting the
 222                 <property>deep</property> option or by using
 223                 <methodname>setOptions()</methodname> . </para>
 224
 225         <programlisting language="php"><![CDATA[
 226 $validator = new Zend_Validate_EmailAddress(
 227     array(
 228         'allow' => Zend_Validate_Hostname::ALLOW_DNS,
 229         'mx'    => true,
 230         'deep'  => true
 231     )
 232 );
 233 ]]></programlisting>
 234
 235         <warning>
 236             <title>Performance warning</title>
 237
 238             <para> You should be aware that enabling MX check will slow down you
 239                 script because of the used network functions. Enabling deep
 240                 check will slow down your script even more as it searches the
 241                 given server for 3 additional types. </para>
 242         </warning>
 243
 244         <note>
 245             <title>Disallowed IP addresses</title>
 246
 247             <para> You should note that MX validation is only accepted for
 248                 external servers. When deep MX validation is enabled, then local
 249                 IP addresses like <command>192.168.*</command> or
 250                     <command>169.254.*</command> are not accepted. </para>
 251         </note>
 252     </sect3>
 253
 254     <sect3 id="zend.validate.set.email_address.validateidn">
 255         <title>Validating International Domains Names</title>
 256
 257         <para>
 258             <classname>Zend_Validate_EmailAddress</classname> también comparará
 259             caracteres internationales que existen en algunos dominios. Esto se
 260             conoce como soporte de International Domain Name (IDN). Está
 261             activado por defecto, aunque puede deshabilitarlo internamente
 262             cambiando el ajuste a través del objeto
 263                 <classname>Zend_Validate_Hostname</classname> que existe en
 264                 <classname>Zend_Validate_EmailAddress</classname> . </para>
 265
 266         <programlisting language="php"><![CDATA[
 267 $validator->getHostnameValidator()->setValidateIdn(false);
 268 ]]></programlisting>
 269
 270         <para> Sobre el uso de <methodname>setValidateIdn()</methodname>
 271             encontrará más información en la documentación de
 272                 <classname>Zend_Validate_Hostname</classname> . </para>
 273
 274         <para> Tenga en cuenta que los IDNs se validarán solo si usted permite
 275             que nombres de host DNS sean validados. </para>
 276     </sect3>
 277
 278     <sect3 id="zend.validate.set.email_address.validatetld">
 279         <title>Validación de dominios de nivel superior</title>
 280
 281         <para> Por defecto, un nombre de host se cotejará con una lista conocida
 282             de TLDs. Está activado por defecto, aunque puede deshabilitarlo
 283             cambiando el ajuste a través del objeto interno
 284                 <classname>Zend_Validate_Hostname</classname> que existe en
 285                 <classname>Zend_Validate_EmailAddress</classname> . </para>
 286
 287         <programlisting language="php"><![CDATA[
 288 $validator->getHostnameValidator()->setValidateTld(false);
 289 ]]></programlisting>
 290
 291         <para> Encontrará más información sobre el uso de
 292                 <methodname>setValidateTld()</methodname> en la documentación de
 293                 <classname>Zend_Validate_Hostname</classname> . </para>
 294
 295         <para> Tenga en cuenta que los TLDs se validarán solo si usted permite
 296             que nombres de host DNS sean validados. </para>
 297     </sect3>
 298
 299     <sect3 id="zend.validate.set.email_address.setmessage">
 300         <title>Setting messages</title>
 301
 302         <para>
 303             <classname>Zend_Validate_EmailAddress</classname> makes also use of
 304                 <classname>Zend_Validate_Hostname</classname> to check the
 305             hostname part of a given email address. As with Zend Framework 1.10
 306             you can simply set messages for
 307                 <classname>Zend_Validate_Hostname</classname> from within
 308                 <classname>Zend_Validate_EmailAddress</classname> . </para>
 309
 310         <programlisting language="php"><![CDATA[
 311 $validator = new Zend_Validate_EmailAddress();
 312 $validator->setMessages(
 313     array(
 314         Zend_Validate_Hostname::UNKNOWN_TLD => 'I don't know the TLD you gave'
 315     )
 316 );
 317 ]]></programlisting>
 318
 319         <para> Before Zend Framework 1.10 you had to attach the messages to your
 320             own <classname>Zend_Validate_Hostname</classname> , and then set
 321             this validator within
 322                 <classname>Zend_Validate_EmailAddress</classname> to get your
 323             own messages returned. </para>
 324     </sect3>
 325 </sect2>