Make IP address optional when reporting transactions

maxmind · May 24, 2024 · 0289ff9 · 0289ff9
1 parent bdad936
commit 0289ff9
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,14 @@
 CHANGELOG
 =========
 
+3.1.0
+------------------
+
+* Updated `MaxMind\MinFraud\ReportTransaction` to make the `ip_address`
+  parameter optional. Now the `tag` and at least one of the following
+  parameters must be supplied: `ip_address`, `maxmind_id`, `minfraud_id`,
+  `transaction_id`.
+
 3.0.1 (2024-05-02)
 ------------------
 

diff --git a/README.md b/README.md
@@ -282,8 +282,9 @@ All externally visible exceptions are in the `\MaxMind\Exception` namespace.
 The possible exceptions are:
 
 * `InvalidInputException` - This will be thrown when the `->report()` method is
-  called with invalid input data or when the required `ip_address` or `tag`
-  fields are missing.
+  called with invalid input data or when the required fields are missing. The
+  required fields are `tag` and one or more of the following: `ip_address`,
+  `maxmind_id`, `minfraud_id`, or `transaction_id`.
 * `AuthenticationException` - This will be thrown on calling `->report()`,
   when the server is unable to authenticate the request, e.g., if the license
   key or account ID is invalid.

diff --git a/src/MinFraud/ReportTransaction.php b/src/MinFraud/ReportTransaction.php
@@ -116,18 +116,25 @@ public function report(
             $this->verifyEmpty($values);
         }
 
+        if ($ipAddress === null && $minfraudId === null &&
+            ($maxmindId === null || $maxmindId === '') &&
+            ($transactionId === null || $transactionId === '')) {
+            throw new InvalidInputException(
+                'The user must pass at least one of the following: ' .
+                'ipAddress, minfraudId, maxmindId, transactionId.'
+            );
+        }
+
         if ($chargebackCode !== null) {
             $values['chargeback_code'] = $chargebackCode;
         }
 
-        if ($ipAddress === null) {
-            // This is required so we always throw an exception if it is not set
-            throw new InvalidInputException('An IP address is required');
-        }
-        if (!filter_var($ipAddress, \FILTER_VALIDATE_IP)) {
-            $this->maybeThrowInvalidInputException("$ipAddress is an invalid IP address");
+        if ($ipAddress !== null) {
+            if (!filter_var($ipAddress, \FILTER_VALIDATE_IP)) {
+                $this->maybeThrowInvalidInputException("$ipAddress is an invalid IP address");
+            }
+            $values['ip_address'] = $ipAddress;
         }
-        $values['ip_address'] = $ipAddress;
 
         if ($maxmindId !== null) {
             if (\strlen($maxmindId) !== 8) {

diff --git a/tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php b/tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php
@@ -62,13 +62,52 @@ public function testRequestsWithNulls(): void
         );
     }
 
+    public function testRequiredFields(): void
+    {
+        $req = [
+            'ip_address' => '1.1.1.1',
+            'tag' => 'not_fraud',
+        ];
+        $this->assertEmpty(
+            $this->createReportTransactionRequest($req, 1)->report($req),
+            'ip_address parameter used'
+        );
+
+        $req = [
+            'maxmind_id' => '12345678',
+            'tag' => 'not_fraud',
+        ];
+        $this->assertEmpty(
+            $this->createReportTransactionRequest($req, 1)->report($req),
+            'maxmind_id parameter used'
+        );
+
+        $req = [
+            'minfraud_id' => '58fa38d8-4b87-458b-a22b-f00eda1aa20d',
+            'tag' => 'not_fraud',
+        ];
+        $this->assertEmpty(
+            $this->createReportTransactionRequest($req, 1)->report($req),
+            'minfraud_id parameter used'
+        );
+
+        $req = [
+            'tag' => 'not_fraud',
+            'transaction_id' => 'abc123',
+        ];
+        $this->assertEmpty(
+            $this->createReportTransactionRequest($req, 1)->report($req),
+            'transaction_id parameter used'
+        );
+    }
+
     /**
      * @dataProvider requestsMissingRequiredFields
      */
     public function testMissingRequiredFields(array $req): void
     {
         $this->expectException(InvalidInputException::class);
-        $this->expectExceptionMessageMatches('/Expected|is required/');
+        $this->expectExceptionMessageMatches('/Expected|is required|must pass at least one of the following/');
 
         $this->createReportTransactionRequest(
             $req,
@@ -82,7 +121,7 @@ public function testMissingRequiredFields(array $req): void
     public function testMissingRequiredFieldsWithoutValidation(array $req): void
     {
         $this->expectException(InvalidInputException::class);
-        $this->expectExceptionMessageMatches('/Expected|is required/');
+        $this->expectExceptionMessageMatches('/Expected|is required|must pass at least one of the following/');
 
         $this->createReportTransactionRequest(
             $req,
@@ -94,7 +133,7 @@ public function testMissingRequiredFieldsWithoutValidation(array $req): void
     public static function requestsMissingRequiredFields(): array
     {
         return [
-            'Missing ip_address' => [
+            'Missing one of ip_address, maxmind_id, minfraud_id, or transaction_id' => [
                 ['tag' => 'not_fraud'],
             ],
             'Missing tag' => [