New service "risk detector", initial functional version. #10

Author: fabiankessler

README.md

@@ -181,3 +181,15 @@ $result = $deaDetector->isDisposable("[email protected]");
 echo $result->getDisposable()->toString()); //will print 'YES'
 ```
 
+
+## Risk Detector
+
+The Risk-Detector checks all data in the person input, including the name, address, birthdate, 
+email address and phone number for fake and suspicious data.
+
+```php
+$riskDetector = $serviceFactory->riskServices()->personRiskDetector();
+$riskResult = $riskDetector->detect($inputPerson);
+var_dump($riskResult);
+```
+

src/org/nameapi/client/services/ServiceFactory.php

@@ -13,6 +13,7 @@
 require_once(__DIR__.'/matcher/MatcherServiceFactory.php');
 require_once(__DIR__.'/formatter/FormatterServiceFactory.php');
 require_once(__DIR__.'/email/EmailServiceFactory.php');
+require_once(__DIR__.'/riskdetector/RiskDetectorServiceFactory.php');
 
 require_once(__DIR__.'/../http/RestHttpClient.php');
 
@@ -59,6 +60,7 @@ class ServiceFactory {
     private $matcherServiceFactory;
     private $formatterServiceFactory;
     private $emailServiceFactory;
+    private $riskServiceFactory;
 
 
     /**
@@ -155,4 +157,15 @@ public function emailServices() {
         return $this->emailServiceFactory;
     }
 
+    /**
+     * @return riskdetector\RiskDetectorServiceFactory
+     * @since v5.3
+     */
+    public function riskServices() {
+        if ($this->riskServiceFactory==null) {
+            $this->riskServiceFactory = new riskdetector\RiskDetectorServiceFactory($this->apiKey, $this->context, $this->baseUrl);
+        }
+        return $this->riskServiceFactory;
+    }
+
 }

src/org/nameapi/client/services/riskdetector/DataItem.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace org\nameapi\client\services\riskdetector;
+
+
+/**
+ * Class DataItem
+ *
+ * Possible values are are listed here.
+ *
+ *
+ * NAME
+ * The person's name (given name, surname, business name ...).
+ *
+ *
+ * ADDRESS
+ * The person's address (domicile, delivery address, ...).
+ *
+ *
+ * AGE
+ * for natural people it's the birth date
+ * for legal people it's the founding time.
+ *
+ *
+ * EMAIL
+ * An email address.
+ *
+ *
+ * TEL
+ * Includes telephone numbers, fax numbers, mobile phone numbers etc.
+ *
+ */
+final class DataItem {
+
+    /**
+     * @var string $value
+     */
+    private $value = null;
+
+    public function __construct($value) {
+        if ($value!=='NAME' && $value!=='ADDRESS' && $value!=='AGE' && $value!=='EMAIL' && $value!=='TEL') {
+            throw new \Exception('Invalid value for RiskType: '.$value.'!');
+        }
+        $this->value = $value;
+    }
+
+
+
+    public function __toString() {
+        return $this->value;
+    }
+
+}
+

src/org/nameapi/client/services/riskdetector/DetectedRisk.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace org\nameapi\client\services\riskdetector;
+
+require_once(__DIR__ . '/DataItem.php');
+require_once(__DIR__ . '/DisguiseRiskType.php');
+require_once(__DIR__ . '/FakeRiskType.php');
+
+/**
+ * One detected risk within a RiskDetectorResult.
+ * There can be 0-n of such risks in one result.
+ *
+ * @since v5.3
+ */
+class DetectedRisk {
+
+    /**
+     * @var DataItem $dataItem
+     */
+    private $dataItem = null;
+
+    /**
+     * @var RiskType $riskType
+     */
+    private $riskType = null;
+
+    /**
+     * @var double $riskScore
+     */
+    private $riskScore = null;
+
+    /**
+     * @var string $reason
+     */
+    private $reason = null;
+
+
+    /**
+     */
+    public function __construct($dataItem, $riskType, $riskScore, $reason) {
+        if ($riskScore <= 0 || $riskScore > 1) throw new \Exception("Risk score is out of range (0,1]: ".$riskScore."!");
+        $this->dataItem = $dataItem;
+        $this->riskType = $riskType;
+        $this->riskScore = $riskScore;
+        $this->reason = $reason;
+    }
+
+
+    /**
+     * @return DataItem
+     */
+    public function getDataItem() {
+        return $this->dataItem;
+    }
+
+    /**
+     * @return RiskType
+     */
+    public function getRiskType() {
+        return $this->riskType;
+    }
+
+    /**
+     * @return float range (0,1] the higher the worse.
+     */
+    public function getRiskScore() {
+        return $this->riskScore;
+    }
+
+    /**
+     * A one sentence text reason intended for the human that explains the risk.
+     */
+    public function getReason() {
+        return $this->reason;
+    }
+
+}
+

src/org/nameapi/client/services/riskdetector/DisguiseRiskType.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace org\nameapi\client\services\riskdetector;
+
+require_once(__DIR__ . '/RiskType.php');
+
+/**
+ * Classification of disguise risks.
+ *
+ * <p>Such mangled input is used to circumvent machine processing.</p>
+ *
+ * <p>Humans can still understand these modified values, but machines can't unless they detect the patterns and clean
+ * the input.</p>
+ *
+ * Possible values are are listed here.
+ *
+ *
+ * PADDING
+ * Padding is adding content to the left/right of a value.
+ * Example: XXXJohnXXX
+ *
+ *
+ * STUTTER_TYPING
+ * Example: Petttttttttterson
+ *
+ *
+ * SPACED_TYPING
+ * Example: P e t e r   M i l l e r
+ *
+ *
+ * OTHER
+ * Everything that does not fit into any of the other categories.
+ * Individual categories may be created in the future.
+ * Currently here goes:
+ *  - Leetspeak (using numbers instead of letters): l33t spe4k
+ *  - Crossing fields (moving a part into the next field): ["Danie", "lJohnson"]
+ *    This often happens unintentionally.
+ *  - Writing out numbers where digits are expected, for example in house numbers.
+ *    For example "twentyseven" instead of "27".
+ *  - Using visually identical or similar letters with different Unicode values.
+ *    Mixing scripts: For example mixing the Cyrillic with the Latin alphabet. Cyrillic has visually identical letters.
+ *    Same script: For example using the lower case L for an upper case i (l vs I) and vice versa, using a zero 0 for an oh O.
+ *
+ */
+final class DisguiseRiskType extends RiskType {
+
+    /**
+     * @var string $value
+     */
+    private $value = null;
+
+    public function __construct($value) {
+        if ($value!=='PADDING' && $value!=='STUTTER_TYPING' && $value!=='SPACED_TYPING' && $value!=='OTHER') {
+            throw new \Exception('Invalid value for RiskType: '.$value.'!');
+        }
+        $this->value = $value;
+    }
+
+
+
+    public function __toString() {
+        return $this->value;
+    }
+
+}
+

src/org/nameapi/client/services/riskdetector/FakeRiskType.php

@@ -0,0 +1,94 @@
+<?php
+
+namespace org\nameapi\client\services\riskdetector;
+
+require_once(__DIR__ . '/RiskType.php');
+
+/**
+ * Classification of risks.
+ *
+ * <p>In some situations the exact classification is difficult.
+ * For example a person's name may be from fiction, but also be famous at the same time.</p>
+ *
+ *
+ * Possible values are are listed here.
+ *
+ *
+ * RANDOM_TYPING
+ * This kind of input is often used to quickly pass mandatory fields in a form.
+ * Example: "asdf asdf".
+ *
+ *
+ * PLACEHOLDER
+ * Examples:
+ * For person name: "John Doe".
+ * For person title: Example: "King Peter"
+ *            The given name field doesn't contain a given name, but has at least a title.
+ *            It may, in addition, contain a salutation.
+ * For salutation: Example: "Mr. Smith" (Mr. in the given name field).
+ *                 The given name field doesn't contain a given name, but has a salutation.
+ *                 There is no title in it, otherwise PLACEHOLDER_TITLE would be used.
+ * For place name: "Anytown"
+ *
+ *
+ * FICTIONAL
+ * Examples:
+ * For natural person: "James Bond".
+ * For legal person: ACME (American Company Making Everything)
+ * For place: "Atlantis", "Entenhausen"
+ *
+ *
+ * FAMOUS
+ * Examples:
+ * For natural person: "Barak Obama".
+ *
+ *
+ * HUMOROUS
+ * For natural person: "Sandy Beach".
+ * Place example: "Timbuckthree"
+ *
+ *
+ * INVALID
+ * This includes multiple types of invalid form input.
+ * Refusing input:
+ * Example: "None of your business"
+ * Placeholder nouns: "Someone", "Somebody else", "Somewhere", "Nowhere"
+ * Repeating the form fields:
+ * Example for person name: "firstname lastname"
+ * Examples for street: "Street"
+ * Vulgar language, swearing
+ * Examples: "fuck off"
+ *
+ *
+ * STRING_SIMILARITY
+ * The given name and surname field are equal or almost equal, or match a certain pattern.
+ * Example: "John" / "John"
+ * The risk score is culture adjusted. In some cultures such names do exist, however, a risk is still raised.
+ *
+ *
+ * OTHER
+ * Everything that does not fit into any of the other categories.
+ *
+ */
+final class FakeRiskType extends RiskType {
+
+    /**
+     * @var string $value
+     */
+    private $value = null;
+
+    public function __construct($value) {
+        if ($value!=='RANDOM_TYPING' && $value!=='PLACEHOLDER' && $value!=='FICTIONAL' && $value!=='FAMOUS' && $value!=='HUMOROUS' && $value!=='INVALID' && $value!=='OTHER') {
+            throw new \Exception('Invalid value for RiskType: '.$value.'!');
+        }
+        $this->value = $value;
+    }
+
+
+
+    public function __toString() {
+        return $this->value;
+    }
+
+}
+