Added email name parser support.

Author: fabiankessler

src/org/nameapi/client/services/email/EmailServiceFactory.php

@@ -4,17 +4,20 @@
 
 use org\nameapi\ontology\input\context\Context;
 use org\nameapi\client\services\email\disposableemailaddressdetector\DisposableEmailAddressDetectorService;
+use org\nameapi\client\services\email\emailnameparser\EmailNameParserService;
 
 require_once('disposableemailaddressdetector/DisposableEmailAddressDetectorService.php');
+require_once('emailnameparser/EmailNameParserService.php');
 
 
 /**
- *
+ * Provides access to the email-related services.
  */
 class EmailServiceFactory {
 
     private $context;
     private $disposableEmailAddressDetector;
+    private $emailNameParser;
 
     /**
      */
@@ -32,4 +35,14 @@ public function disposableEmailAddressDetector() {
         return $this->disposableEmailAddressDetector;
     }
 
+    /**
+     * @return EmailNameParserService
+     */
+    public function emailNameParser() {
+        if ($this->emailNameParser==null) {
+            $this->emailNameParser = new EmailNameParserService($this->context);
+        }
+        return $this->emailNameParser;
+    }
+
 }

src/org/nameapi/client/services/email/disposableemailaddressdetector/wsdl/DisposableEmailAddressDetectorArguments.php

@@ -10,12 +10,10 @@ class DisposableEmailAddressDetectorArguments {
     public $emailAddress = null;
 
     /**
-     *
      * @param Context $context
      * @param string $emailAddress
-     * @access public
      */
-    public function __construct($context, $emailAddress) {
+    public function __construct(Context $context, $emailAddress) {
         $this->context = $context;
         $this->emailAddress = $emailAddress;
     }

src/org/nameapi/client/services/email/disposableemailaddressdetector/wsdl/SoapDisposableEmailAddressDetectorService.php

@@ -23,10 +23,8 @@ class SoapDisposableEmailAddressDetectorService extends BaseSoapClient {
     );
 
     /**
-     *
      * @param array $options A array of config values
      * @param string $wsdl The wsdl file to use
-     * @access public
      */
     public function __construct(array $options = array(), $wsdl = 'http://api.nameapi.org/soap/v4.0/email/disposableemailaddressdetector?wsdl') {
         parent::__construct($wsdl, self::$classmap, $options);

src/org/nameapi/client/services/email/emailnameparser/EmailAddressNameType.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+/**
+ * Class EmailAddressParsingResultType
+ *
+ * Possible values are: NAME, INITIAL
+ */
+class EmailAddressNameType {
+
+    /**
+     * @var string $value
+     */
+    private $value = null;
+
+    public function __construct($value) {
+        if ($value!=='NAME'
+            && $value!=='INITIAL'
+        ) {
+            throw new \Exception('Invalid value for EmailAddressNameType: '.$value.'!');
+        }
+        $this->value = $value;
+    }
+
+
+    public function toString() {
+        return $this->value;
+    }
+    public function __toString() {
+        return $this->toString();
+    }
+
+} 

src/org/nameapi/client/services/email/emailnameparser/EmailAddressParsingResultType.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+
+/**
+ * Class EmailAddressParsingResultType
+ *
+ * Possible values are:
+ *
+ * DEPARTMENT
+ * The email address belongs to a department, such as [email protected].
+ *
+ * TECHNICAL
+ * It is a technical email address for the domain, such as [email protected].
+ *
+ * INITIALS
+ * The email address contains a person's initials such as [email protected].
+ * <p>Note that this answer is a guess, the 2 letters could also have another meaning
+ * such as a short given name or surname, or something completely different.</p>
+ *
+ * PERSON_NAME
+ * The email address contains a person's name such as [email protected].
+ *
+ * PSEUDONYM
+ * The email address uses a pseudonym as the user name such as [email protected] or [email protected].
+ *
+ * NOT_A_NAME
+ * There is no name in the address, for example [email protected]
+ * <p>The address may be personal or non-personal, can't say (as in UNKNOWN)
+ * but it is clear that no name can be found in it.</p>
+ *
+ * UNKNOWN
+ * The email address could not be classified and hence the service failed to extract a name.
+ *
+ *
+ */
+final class EmailAddressParsingResultType {
+
+    /**
+     * @var string $value
+     */
+    private $value = null;
+
+    public function __construct($value) {
+        if ($value!=='DEPARTMENT'
+            && $value!=='TECHNICAL'
+            && $value!=='INITIALS'
+            && $value!=='PERSON_NAME'
+            && $value!=='PSEUDONYM'
+            && $value!=='NOT_A_NAME'
+            && $value!=='UNKNOWN'
+        ) {
+            throw new \Exception('Invalid value for EmailAddressParsingResultType: '.$value.'!');
+        }
+        $this->value = $value;
+    }
+
+
+    public function toString() {
+        return $this->value;
+    }
+    public function __toString() {
+        return $this->toString();
+    }
+
+}
+

src/org/nameapi/client/services/email/emailnameparser/EmailNameParserMatch.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+require_once('NameFromEmailAddress.php');
+
+/**
+ * One way (and ideally the only way) of parsing an email address.
+ */
+class EmailNameParserMatch {
+
+    /**
+     * @var NameFromEmailAddress[] $givenNames
+     */
+    private $givenNames = null;
+
+    /**
+     * @var NameFromEmailAddress[] $surnames
+     */
+    private $surnames = null;
+
+    /**
+     * @var float $confidence
+     */
+    private $confidence = null;
+
+
+    /**
+     * @param NameFromEmailAddress[] $givenNames
+     * @param NameFromEmailAddress[] $surnames
+     * @param float $confidence
+     */
+    public function __construct($givenNames, $surnames, $confidence) {
+        $this->givenNames = $givenNames;
+        $this->surnames = $surnames;
+        $this->confidence = $confidence;
+    }
+
+    /**
+     * @return NameFromEmailAddress[]
+     */
+    public function getGivenNames() {
+        return $this->givenNames;
+    }
+
+    /**
+     * @return NameFromEmailAddress[]
+     */
+    public function getSurnames() {
+        return $this->surnames;
+    }
+
+    /**
+     * @return float 0-1
+     */
+    public function getConfidence() {
+        return $this->confidence;
+    }
+
+} 

src/org/nameapi/client/services/email/emailnameparser/EmailNameParserResult.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+require_once('EmailAddressParsingResultType.php');
+require_once('EmailNameParserMatch.php');
+
+class EmailNameParserResult {
+
+    /**
+     * @var EmailAddressParsingResultType
+     */
+    private $resultType = null;
+
+    /**
+     * @var EmailNameParserMatch[] $matches
+     */
+    private $matches = null;
+
+
+    /**
+     * @param EmailAddressParsingResultType $resultType
+     * @param EmailNameParserMatch[] $matches
+     */
+    public function __construct(EmailAddressParsingResultType $resultType, $matches) {
+        $this->resultType = $resultType;
+        $this->matches = $matches;
+    }
+
+    /**
+     * @return EmailAddressParsingResultType
+     */
+    public function getResultType() {
+        return $this->resultType;
+    }
+
+    /**
+     * @return EmailNameParserMatch[]
+     */
+    public function getMatches() {
+        return $this->matches;
+    }
+
+} 

src/org/nameapi/client/services/email/emailnameparser/EmailNameParserService.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+use org\nameapi\ontology\input\context\Context;
+
+require_once('wsdl/SoapEmailNameParserService.php');
+require_once('EmailNameParserResult.php');
+
+/**
+ * This is the service class for the web service offered at
+ * http://api.nameapi.org/soap/v4.0/email/emailnameparser?wsdl
+ *
+ * HOW TO USE:
+ * $emailNameParser = $myServiceFactory->emailServices()->emailNameParser();
+ * $result = $emailNameParser->parse("[email protected]");
+ * echo $result->getDisposable()->toString()); //will print 'YES'
+ */
+class EmailNameParserService {
+
+    private $context;
+    private $soapEmailNameParserService;
+
+    public function __construct(Context $context) {
+        $this->context = $context;
+        $this->soapEmailNameParserService = new wsdl\SoapEmailNameParserService();
+    }
+
+    /**
+     * @param string $emailAddress
+     * @return EmailNameParserResult
+     */
+    public function parse($emailAddress) {
+        $parameters = new wsdl\EmailNameParserServiceArguments($this->context, $emailAddress);
+        $result = $this->soapEmailNameParserService->parse($parameters);
+        $matches = array();
+        if (isSet($result->return->matches)) {
+            foreach ($result->return->matches as $match) {
+                $givenNames = array();
+                $surnames   = array();
+                if (isSet($match->givenNames)) {
+                    foreach ($match->givenNames as $name) {
+                        array_push($givenNames, new NameFromEmailAddress($name->name, new EmailAddressNameType($name->nameType)));
+                    }
+                }
+                if (isSet($match->surnames)) {
+                    foreach ($match->surnames as $name) {
+                        array_push($surnames, new NameFromEmailAddress($name->name, new EmailAddressNameType($name->nameType)));
+                    }
+                }
+                array_push($matches, new EmailNameParserMatch($givenNames, $surnames, $match->confidence));
+            }
+        }
+        return new EmailNameParserResult(
+            new EmailAddressParsingResultType($result->return->resultType),
+            $matches
+        );
+    }
+
+} 

src/org/nameapi/client/services/email/emailnameparser/NameFromEmailAddress.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace org\nameapi\client\services\email\emailnameparser;
+
+require_once('EmailAddressNameType.php');
+
+class NameFromEmailAddress {
+
+    /**
+     * @var string $name
+     */
+    private $name = null;
+
+    /**
+     * @var EmailAddressNameType $nameType
+     */
+    private $nameType = null;
+
+
+    /**
+     * @param string[] $name
+     * @param EmailAddressNameType $nameType
+     */
+    public function __construct($name, EmailAddressNameType $nameType) {
+        $this->name = $name;
+        $this->nameType = $nameType;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName() {
+        return $this->name;
+    }
+
+    /**
+     * @return EmailAddressNameType
+     */
+    public function getNameType() {
+        return $this->nameType;
+    }
+
+}