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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect2 id="zend.validate.set.email_address">
   4     <title>EmailAddress</title>
   5
   6     <para>
   7         <classname>Zend_Validate_EmailAddress</classname> allows you to validate an email address.
   8         The validator first splits the email address on local-part @ hostname and attempts to match
   9         these against known specifications for email addresses and hostnames.
  10     </para>
  11
  12     <sect3 id="zend.validate.set.email_address.basic">
  13         <title>Basic usage</title>
  14
  15         <para>
  16             A basic example of usage is below:
  17         </para>
  18
  19         <programlisting language="php"><![CDATA[
  20 $validator = new Zend_Validate_EmailAddress();
  21 if ($validator->isValid($email)) {
  22     // email appears to be valid
  23 } else {
  24     // email is invalid; print the reasons
  25     foreach ($validator->getMessages() as $message) {
  26         echo "$message\n";
  27     }
  28 }
  29 ]]></programlisting>
  30
  31         <para>
  32             This will match the email address <varname>$email</varname> and on failure populate
  33             <code>$validator->getMessages()</code> with useful error messages.
  34         </para>
  35     </sect3>
  36
  37     <sect3 id="zend.validate.set.email_address.options">
  38         <title>Options for validating Email Addresses</title>
  39
  40         <para>
  41             <classname>Zend_Validate_EmailAddress</classname> supports several options which can
  42             either be set at initiation, by giving an array with the related options, or
  43             afterwards, by using <methodname>setOptions()</methodname>. The following options are
  44             supported:
  45         </para>
  46
  47         <itemizedlist>
  48             <listitem>
  49                 <para>
  50                     <emphasis><property>allow</property></emphasis>: Defines which type of domain
  51                     names are accepted. This option is used in conjunction with the hostname option
  52                     to set the hostname validator. For more informations about possible values of
  53                     this option, look at <link linkend="zend.validate.set.hostname">Hostname</link>
  54                     and possible <constant>ALLOW</constant>* constants. This option defaults to
  55                     <constant>ALLOW_DNS</constant>.
  56                 </para>
  57             </listitem>
  58
  59             <listitem>
  60                 <para>
  61                     <emphasis><property>deep</property></emphasis>: Defines if the servers MX
  62                     records should be verified by a deep check. When this option is set to
  63                     <constant>TRUE</constant> then additionally to MX records also the A, A6 and
  64                     <constant>AAAA</constant> records are used to verify if the server accepts
  65                     emails. This option defaults to <constant>FALSE</constant>.
  66                 </para>
  67             </listitem>
  68
  69             <listitem>
  70                 <para>
  71                     <emphasis><property>domain</property></emphasis>: Defines if the domain part
  72                     should be checked. When this option is set to <constant>FALSE</constant>, then
  73                     only the local part of the email address will be checked. In this case the
  74                     hostname validator will not be called. This option defaults to
  75                     <constant>TRUE</constant>.
  76                 </para>
  77             </listitem>
  78
  79             <listitem>
  80                 <para>
  81                     <emphasis><property>hostname</property></emphasis>: Sets the hostname validator
  82                     with which the domain part of the email address will be validated.
  83                 </para>
  84             </listitem>
  85
  86             <listitem>
  87                 <para>
  88                     <emphasis><property>mx</property></emphasis>: Defines if the MX records from the
  89                     server should be detected. If this option is defined to
  90                     <constant>TRUE</constant> then the MX records are used to verify if the server
  91                     accepts emails. This option defaults to <constant>FALSE</constant>.
  92                 </para>
  93             </listitem>
  94         </itemizedlist>
  95
  96         <programlisting language="php"><![CDATA[
  97 $validator = new Zend_Validate_EmailAddress();
  98 $validator->setOptions(array('domain' => false));
  99 ]]></programlisting>
 100     </sect3>
 101
 102     <sect3 id="zend.validate.set.email_address.complexlocal">
 103         <title>Complex local parts</title>
 104
 105         <para>
 106             <classname>Zend_Validate_EmailAddress</classname> will match any valid email address
 107             according to RFC2822. For example, valid emails include <code>bob@domain.com</code>,
 108             <code>bob+jones@domain.us</code>, <code>"bob@jones"@domain.com</code> and
 109             <code>"bob jones"@domain.com</code>
 110         </para>
 111
 112         <para>
 113             Some obsolete email formats will not currently validate (e.g. carriage returns or a
 114             "\" character in an email address).
 115         </para>
 116     </sect3>
 117
 118     <sect3 id="zend.validate.set.email_address.purelocal">
 119         <title>Validating only the local part</title>
 120
 121         <para>
 122             If you need <classname>Zend_Validate_EmailAddress</classname> to check only the local
 123             part of an email address, and want to disable validation of the hostname, you can
 124             set the <property>domain</property> option to <constant>FALSE</constant>. This forces
 125             <classname>Zend_Validate_EmailAddress</classname> not to validate the hostname part of
 126             the email address.
 127         </para>
 128
 129         <programlisting language="php"><![CDATA[
 130 $validator = new Zend_Validate_EmailAddress();
 131 $validator->setOptions(array('domain' => FALSE));
 132 ]]></programlisting>
 133     </sect3>
 134
 135     <sect3 id="zend.validate.set.email_address.hostnametype">
 136         <title>Validating different types of hostnames</title>
 137
 138         <para>
 139             The hostname part of an email address is validated against <link
 140                 linkend="zend.validate.set.hostname">
 141                 <classname>Zend_Validate_Hostname</classname></link>. By default
 142             only DNS hostnames of the form <code>domain.com</code> are accepted, though if you wish
 143             you can accept IP addresses and Local hostnames too.
 144         </para>
 145
 146         <para>
 147             To do this you need to instantiate <classname>Zend_Validate_EmailAddress</classname>
 148             passing a parameter to indicate the type of hostnames you want to accept. More details
 149             are included in <classname>Zend_Validate_Hostname</classname>, though an example of how
 150             to accept both DNS and Local hostnames appears below:
 151         </para>
 152
 153         <programlisting language="php"><![CDATA[
 154 $validator = new Zend_Validate_EmailAddress(
 155                     Zend_Validate_Hostname::ALLOW_DNS |
 156                     Zend_Validate_Hostname::ALLOW_LOCAL);
 157 if ($validator->isValid($email)) {
 158     // email appears to be valid
 159 } else {
 160     // email is invalid; print the reasons
 161     foreach ($validator->getMessages() as $message) {
 162         echo "$message\n";
 163     }
 164 }
 165 ]]></programlisting>
 166     </sect3>
 167
 168     <sect3 id="zend.validate.set.email_address.checkacceptance">
 169         <title>Checking if the hostname actually accepts email</title>
 170
 171         <para>
 172             Just because an email address is in the correct format, it doesn't necessarily mean
 173             that email address actually exists. To help solve this problem, you can use MX
 174             validation to check whether an MX (email) entry exists in the DNS record for the
 175             email's hostname. This tells you that the hostname accepts email, but doesn't tell you
 176             the exact email address itself is valid.
 177         </para>
 178
 179         <para>
 180             MX checking is not enabled by default. To enable MX checking you can pass a second
 181             parameter to the <classname>Zend_Validate_EmailAddress</classname> constructor.
 182         </para>
 183
 184         <programlisting language="php"><![CDATA[
 185 $validator = new Zend_Validate_EmailAddress(
 186     array(
 187         'allow' => Zend_Validate_Hostname::ALLOW_DNS,
 188         'mx'    => true
 189     )
 190 );
 191 ]]></programlisting>
 192
 193         <note>
 194             <title>MX Check under Windows</title>
 195
 196             <para>
 197                 Within Windows environments MX checking is only available when
 198                 <acronym>PHP</acronym> 5.3 or above is used. Below <acronym>PHP</acronym> 5.3 MX
 199                 checking will not be used even if it's activated within the options.
 200             </para>
 201         </note>
 202
 203         <para>
 204             Alternatively you can either pass <constant>TRUE</constant> or
 205             <constant>FALSE</constant> to <code>$validator->setValidateMx()</code> to enable or
 206             disable MX validation.
 207         </para>
 208
 209         <para>
 210             By enabling this setting network functions will be used to check for the presence of an
 211             MX record on the hostname of the email address you wish to validate. Please be aware
 212             this will likely slow your script down.
 213         </para>
 214
 215         <para>
 216             Sometimes validation for MX records returns <constant>FALSE</constant>, even if emails
 217             are accepted. The reason behind this behaviour is, that servers can accept emails even
 218             if they do not provide a MX record. In this case they can provide A, A6 or
 219             <constant>AAAA</constant> records. To allow
 220             <classname>Zend_Validate_EmailAddress</classname> to check also for these other records,
 221             you need to set deep MX validation. This can be done at initiation by setting the
 222             <property>deep</property> option or by using <methodname>setOptions()</methodname>.
 223         </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>
 239                 You should be aware that enabling MX check will slow down you script because of the
 240                 used network functions. Enabling deep check will slow down your script even more as
 241                 it searches the given server for 3 additional types.
 242             </para>
 243         </warning>
 244
 245         <note>
 246             <title>Disallowed IP addresses</title>
 247
 248             <para>
 249                 You should note that MX validation is only accepted for external servers. When deep
 250                 MX validation is enabled, then local IP addresses like <command>192.168.*</command>
 251                 or <command>169.254.*</command> are not accepted.
 252             </para>
 253         </note>
 254     </sect3>
 255
 256     <sect3 id="zend.validate.set.email_address.validateidn">
 257         <title>Validating International Domains Names</title>
 258
 259         <para>
 260             <classname>Zend_Validate_EmailAddress</classname> will also match international
 261             characters that exist in some domains. This is known as International Domain Name (IDN)
 262             support. This is enabled by default, though you can disable this by changing the
 263             setting via the internal <classname>Zend_Validate_Hostname</classname> object that
 264             exists within <classname>Zend_Validate_EmailAddress</classname>.
 265         </para>
 266
 267         <programlisting language="php"><![CDATA[
 268 $validator->getHostnameValidator()->setValidateIdn(false);
 269 ]]></programlisting>
 270
 271         <para>
 272             More information on the usage of <methodname>setValidateIdn()</methodname> appears in
 273             the <classname>Zend_Validate_Hostname</classname> documentation.
 274         </para>
 275
 276         <para>
 277             Please note IDNs are only validated if you allow DNS hostnames to be validated.
 278         </para>
 279     </sect3>
 280
 281     <sect3 id="zend.validate.set.email_address.validatetld">
 282         <title>Validating Top Level Domains</title>
 283
 284         <para>
 285             By default a hostname will be checked against a list of known TLDs. This is enabled by
 286             default, though you can disable this by changing the setting via the internal
 287             <classname>Zend_Validate_Hostname</classname> object that exists within
 288             <classname>Zend_Validate_EmailAddress</classname>.
 289         </para>
 290
 291         <programlisting language="php"><![CDATA[
 292 $validator->getHostnameValidator()->setValidateTld(false);
 293 ]]></programlisting>
 294
 295         <para>
 296             More information on the usage of <methodname>setValidateTld()</methodname> appears in
 297             the <classname>Zend_Validate_Hostname</classname> documentation.
 298         </para>
 299
 300         <para>
 301             Please note TLDs are only validated if you allow DNS hostnames to be validated.
 302         </para>
 303     </sect3>
 304
 305     <sect3 id="zend.validate.set.email_address.setmessage">
 306         <title>Setting messages</title>
 307
 308         <para>
 309             <classname>Zend_Validate_EmailAddress</classname> makes also use of
 310             <classname>Zend_Validate_Hostname</classname> to check the hostname part of a given
 311             email address. As with Zend Framework 1.10 you can simply set messages for
 312             <classname>Zend_Validate_Hostname</classname> from within
 313             <classname>Zend_Validate_EmailAddress</classname>.
 314         </para>
 315
 316         <programlisting language="php"><![CDATA[
 317 $validator = new Zend_Validate_EmailAddress();
 318 $validator->setMessages(
 319     array(
 320         Zend_Validate_Hostname::UNKNOWN_TLD => 'I don't know the TLD you gave'
 321     )
 322 );
 323 ]]></programlisting>
 324
 325         <para>
 326             Before Zend Framework 1.10 you had to attach the messages to your own
 327             <classname>Zend_Validate_Hostname</classname>, and then set this validator within
 328             <classname>Zend_Validate_EmailAddress</classname> to get your own messages returned.
 329         </para>
 330     </sect3>
 331 </sect2>
 332 <!--
 333 vim:se ts=4 sw=4 et:
 334 -->