Added EmailValidatorInterface (#120)

Fixes #91 and #74 for v1.2.x

.travis.yml

@@ -12,15 +12,17 @@ php:
 
 env:
   global:
-    - deps=no
+    - deps=high
 
 matrix:
   fast_finish: true
   include:
     - php: 5.3
       env: deps=low
-    - php: 5.6
-      env: deps=high
+    - php: 5.4
+      env: deps=no
+    - php: 5.5
+      env: deps=no
 
 install:
   - if [ "$deps" = "no" ]; then composer install; fi
@@ -31,6 +33,3 @@ script:
  - mkdir -p build/logs
  - phpunit --coverage-clover build/logs/clover.xml
 
-after_script:
- - php vendor/bin/coveralls
-

composer.json

@@ -15,11 +15,10 @@
   },
   "require":      {
     "php": ">= 5.3.3",
-    "doctrine/lexer": "~1.0,>=1.0.1"
+    "doctrine/lexer": "^1.0.1"
   },
   "require-dev" :   {
-    "satooshi/php-coveralls": "dev-master",
-    "phpunit/phpunit": "~4.4"
+    "phpunit/phpunit": "^4.8.24"
   },
   "autoload": {
     "psr-0": {

src/Egulias/EmailValidator/EmailValidator.php

@@ -7,50 +7,52 @@ namespace Egulias\EmailValidator;
  *
  * @author Eduardo Gulias Davis <me@egulias.com>
  */
-class EmailValidator
+class EmailValidator implements EmailValidatorInterface
 {
+    /**
+     * Critical validation errors used to indicate that
+     * an email address is invalid:
+     */
     const ERR_CONSECUTIVEATS     = 128;
     const ERR_EXPECTING_DTEXT    = 129;
     const ERR_NOLOCALPART        = 130;
     const ERR_NODOMAIN           = 131;
     const ERR_CONSECUTIVEDOTS    = 132;
     const ERR_ATEXT_AFTER_CFWS   = 133;
-    const ERR_ATEXT_AFTER_QS     = 134;
-    const ERR_ATEXT_AFTER_DOMLIT = 135;
     const ERR_EXPECTING_QPAIR    = 136;
     const ERR_EXPECTING_ATEXT    = 137;
-    const ERR_EXPECTING_QTEXT    = 138;
     const ERR_EXPECTING_CTEXT    = 139;
-    const ERR_BACKSLASHEND       = 140;
     const ERR_DOT_START          = 141;
     const ERR_DOT_END            = 142;
-    const ERR_DOMAINHYPHENSTART  = 143;
     const ERR_DOMAINHYPHENEND    = 144;
     const ERR_UNCLOSEDQUOTEDSTR  = 145;
     const ERR_UNCLOSEDCOMMENT    = 146;
-    const ERR_UNCLOSEDDOMLIT     = 147;
     const ERR_FWS_CRLF_X2        = 148;
     const ERR_FWS_CRLF_END       = 149;
     const ERR_CR_NO_LF           = 150;
     const ERR_DEPREC_REACHED     = 151;
     const ERR_UNOPENEDCOMMENT    = 152;
+    const ERR_ATEXT_AFTER_QS     = 134; // not in use
+    const ERR_ATEXT_AFTER_DOMLIT = 135; // not in use
+    const ERR_EXPECTING_QTEXT    = 138; // not in use
+    const ERR_BACKSLASHEND       = 140; // not in use
+    const ERR_DOMAINHYPHENSTART  = 143; // not in use
+    const ERR_UNCLOSEDDOMLIT     = 147; // not in use
+
+    /**
+     * Informational validation warnings regarding unusual or
+     * deprecated features found in an email address:
+     */
+    // Address is valid for SMTP (RFC-5321), but has unusual elements.
     const RFC5321_TLD             = 9;
-    const RFC5321_TLDNUMERIC      = 10;
     const RFC5321_QUOTEDSTRING    = 11;
     const RFC5321_ADDRESSLITERAL  = 12;
     const RFC5321_IPV6DEPRECATED  = 13;
-    const CFWS_COMMENT            = 17;
-    const CFWS_FWS                = 18;
-    const DEPREC_LOCALPART        = 33;
-    const DEPREC_FWS              = 34;
-    const DEPREC_QTEXT            = 35;
-    const DEPREC_QP               = 36;
-    const DEPREC_COMMENT          = 37;
-    const DEPREC_CTEXT            = 38;
-    const DEPREC_CFWS_NEAR_AT     = 49;
+    const RFC5321_TLDNUMERIC      = 10; // not in use
+    // Address is only valid according to the broad
+    // definition of RFC-5322. It is otherwise invalid.
     const RFC5322_LOCAL_TOOLONG   = 64;
     const RFC5322_LABEL_TOOLONG   = 63;
-    const RFC5322_DOMAIN          = 65;
     const RFC5322_TOOLONG         = 66;
     const RFC5322_DOMAIN_TOOLONG  = 255;
     const RFC5322_DOMAINLITERAL   = 70;
@@ -61,12 +63,48 @@ class EmailValidator
     const RFC5322_IPV6_MAXGRPS    = 75;
     const RFC5322_IPV6_COLONSTRT  = 76;
     const RFC5322_IPV6_COLONEND   = 77;
+    const RFC5322_DOMAIN          = 65; // not in use
+    // Address contains deprecated elements, but may
+    // still be valid in restricted contexts.
+    const DEPREC_QP               = 36;
+    const DEPREC_COMMENT          = 37;
+    const DEPREC_CFWS_NEAR_AT     = 49;
+    const DEPREC_LOCALPART        = 33; // not in use
+    const DEPREC_FWS              = 34; // not in use
+    const DEPREC_QTEXT            = 35; // not in use
+    const DEPREC_CTEXT            = 38; // not in use
+    // Address is valid within the message,
+    // but cannot be used unmodified in the envelope.
+    const CFWS_COMMENT            = 17;
+    const CFWS_FWS                = 18;
+    // Hostname DNS checks were unsuccessful.
     const DNSWARN_NO_MX_RECORD    = 5;
     const DNSWARN_NO_RECORD       = 6;
 
+    /**
+     * @var EmailParser
+     */
     protected $parser;
+
+    /**
+     * Contains any informational warnings regarding unusual/deprecated
+     * features that were encountered during validation.
+     *
+     * @var array
+     */
     protected $warnings = array();
+
+    /**
+     * If a critical validation problem is encountered, this will be
+     * set to the value of one of this class's ERR_* constants.
+     *
+     * @var int
+     */
     protected $error;
+
+    /**
+     * @var int
+     */
     protected $threshold = 255;
 
     public function __construct()
@@ -74,6 +112,9 @@ class EmailValidator
         $this->parser = new EmailParser(new EmailLexer());
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function isValid($email, $checkDNS = false, $strict = false)
     {
         try {
@@ -85,22 +126,18 @@ class EmailValidator
             return false;
         }
 
-        $dns = true;
-        if ($checkDNS) {
-            $dns = $this->checkDNS();
-        }
+        $dnsProblemExists = ($checkDNS ? !$this->checkDNS() : false);
 
         if ($this->hasWarnings() && ((int) max($this->warnings) > $this->threshold)) {
             $this->error = self::ERR_DEPREC_REACHED;
-
             return false;
         }
 
-        return !$strict || (!$this->hasWarnings() && $dns);
+        return ($strict ? (!$this->hasWarnings() && !$dnsProblemExists) : true);
     }
 
     /**
-     * @return boolean
+     * {@inheritdoc}
      */
     public function hasWarnings()
     {
@@ -108,7 +145,7 @@ class EmailValidator
     }
 
     /**
-     * @return array
+     * {@inheritdoc}
      */
     public function getWarnings()
     {
@@ -116,7 +153,7 @@ class EmailValidator
     }
 
     /**
-     * @return string
+     * {@inheritdoc}
      */
     public function getError()
     {
@@ -124,9 +161,7 @@ class EmailValidator
     }
 
     /**
-     * @param int $threshold
-     *
-     * @return EmailValidator
+     * {@inheritdoc}
      */
     public function setThreshold($threshold)
     {
@@ -136,26 +171,27 @@ class EmailValidator
     }
 
     /**
-     * @return int
+     * {@inheritdoc}
      */
     public function getThreshold()
     {
         return $this->threshold;
     }
 
+    /**
+     * @return bool Whether or not an MX record exists for the
+     *              email address's host name.
+     */
     protected function checkDNS()
     {
-        $checked = true;
+        $mxRecordExists = checkdnsrr(trim($this->parser->getParsedDomainPart()), 'MX');
 
-        $result = checkdnsrr(trim($this->parser->getParsedDomainPart()), 'MX');
-
-        if (!$result) {
+        if (!$mxRecordExists) {
             $this->warnings[] = self::DNSWARN_NO_RECORD;
-            $checked = false;
             $this->addTLDWarnings();
         }
 
-        return $checked;
+        return $mxRecordExists;
     }
 
     protected function addTLDWarnings()

src/Egulias/EmailValidator/EmailValidatorInterface.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace Egulias\EmailValidator;
+
+/**
+ * EmailValidatorInterface
+ *
+ * @author Chris McCafferty <cilefen@gmail.com>
+ */
+interface EmailValidatorInterface
+{
+    /**
+     * Validates an email address against the following standards:
+     *
+     * RFC-5321: Simple Mail Transfer Protocol
+     * RFC-5322: Internet Message Format
+     * RFC-6530: Overview and Framework for Internationalized Email
+     * RFC-6531: SMTP Extension for Internationalized Email
+     * RFC-6532: Internationalized Email Headers
+     * RFC-1123 section 2.1: Requirements for Internet Hosts -- Application and Support
+     * RFC-4291 section 2.2: IP Version 6 Addressing Architecture
+     *
+     * @param string $email    The email address to validate.
+     * @param bool   $checkDNS Whether or not the email address's hostname should
+     *                         be confirmed with a DNS lookup. This only comes
+     *                         into play if strict mode is also enabled.
+     * @param bool   $strict   If this is true, and any informational warnings
+     *                         were raised during validation, the email address
+     *                         will be considered invalid. Additionally, if
+     *                         $checkDNS is true and the DNS lookup failed,
+     *                         the email address will be considered invalid.
+     * @return bool
+     */
+    public function isValid($email, $checkDNS = false, $strict = false);
+
+    /**
+     * @return bool
+     */
+    public function hasWarnings();
+
+    /**
+     * @return array
+     */
+    public function getWarnings();
+
+    /**
+     * @return string
+     */
+    public function getError();
+
+    /**
+     * @param int $threshold The acceptable number of deprecation warnings.
+     *
+     * @return EmailValidator
+     */
+    public function setThreshold($threshold);
+
+    /**
+     * @return int
+     */
+    public function getThreshold();
+}

src/Egulias/EmailValidator/Parser/DomainPart.php

@@ -107,9 +107,7 @@ class DomainPart extends Parser
         do {
             $prev = $this->lexer->getPrevious();
 
-            if ($this->lexer->token['type'] === EmailLexer::S_SLASH) {
-                throw new \InvalidArgumentException('ERR_DOMAIN_CHAR_NOT_ALLOWED');
-            }
+            $this->checkNotAllowedChars($this->lexer->token);
 
             if ($this->lexer->token['type'] === EmailLexer::S_OPENPARENTHESIS) {
                 $this->parseComments();
@@ -148,6 +146,14 @@ class DomainPart extends Parser
         return $domain;
     }
 
+    private function checkNotAllowedChars($token)
+    {
+        $notAllowed = array(EmailLexer::S_BACKSLASH => true, EmailLexer::S_SLASH=> true);
+        if (isset($notAllowed[$token['type']])) {
+            throw new \InvalidArgumentException('ERR_DOMAIN_CHAR_NOT_ALLOWED');
+        }
+    }
+
     protected function parseDomainLiteral()
     {
         if ($this->lexer->isNextToken(EmailLexer::S_COLON)) {

tests/egulias/Tests/EmailValidator/EmailValidatorTest.php

@@ -64,6 +64,7 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
             array('test@email%'),
             array('test@email$'),
             array('test@email.com.au'),
+            array('1500111@профи-инвест.рф'),
         );
     }
 
@@ -88,6 +89,7 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
             array('.example@localhost'),
             array('ex\ample@localhost'),
             array('example@local\host'),
+            array('example@localhost\\'),
             array('example@localhost.'),
             array('user name@example.com'),
             array('username@ example . com'),
@@ -201,21 +203,21 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
                     EmailValidator::DEPREC_CFWS_NEAR_AT,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                'example @example.co.uk'
+                'example @invalid.example.com'
             ),
             array(
                 array(
                     EmailValidator::DEPREC_CFWS_NEAR_AT,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                'example@ example.co.uk'
+                'example@ invalid.example.com'
             ),
             array(
                 array(
                     EmailValidator::CFWS_COMMENT,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                'example@example(examplecomment).co.uk'
+                'example@invalid.example(examplecomment).com'
             ),
             array(
                 array(
@@ -223,7 +225,7 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
                     EmailValidator::DEPREC_CFWS_NEAR_AT,
                     EmailValidator::DNSWARN_NO_RECORD,
                 ),
-                'example(examplecomment)@example.co.uk'
+                'example(examplecomment)@invalid.example.com'
             ),
             array(
                 array(
@@ -231,7 +233,7 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
                     EmailValidator::CFWS_FWS,
                     EmailValidator::DNSWARN_NO_RECORD,
                 ),
-                "\"\t\"@example.co.uk"
+                "\"\t\"@invalid.example.com"
             ),
             array(
                 array(
@@ -239,7 +241,7 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
                     EmailValidator::CFWS_FWS,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                "\"\r\"@example.co.uk"
+                "\"\r\"@invalid.example.com"
             ),
             array(
                 array(
@@ -331,14 +333,14 @@ class EmailValidatorTest extends \PHPUnit_Framework_TestCase
                     EmailValidator::RFC5321_QUOTEDSTRING,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                '"example"@example.co.uk'
+                '"example"@invalid.example.com'
             ),
             array(
                 array(
                     EmailValidator::RFC5322_LOCAL_TOOLONG,
                     EmailValidator::DNSWARN_NO_RECORD
                 ),
-                'too_long_localpart_too_long_localpart_too_long_localpart_too_long_localpart@example.co.uk'
+                'too_long_localpart_too_long_localpart_too_long_localpart_too_long_localpart@invalid.example.com'
             ),
             array(
                 array(