Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make IP address optional when reporting transactions #175

Merged
merged 4 commits into from
Jun 6, 2024
Merged

Make IP address optional when reporting transactions #175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a0f49df
Make IP address optional when reporting transactions
ugexe May 24, 2024
77bd5bf
Do one-of field validation after individual field validation
ugexe May 30, 2024
364fb64
Check for empty values
ugexe May 30, 2024
6cbfc42
Clean up documentation
ugexe May 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: `ipAddress`, `maxmindId`, `minfraudId`,
`transactionId`.

3.0.1 (2024-05-02)
------------------

Expand Down
5 changes: 3 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: `ipAddress`,
`maxmindId`, `minfraudId`, or `transactionId`.
* `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.
Expand Down
50 changes: 33 additions & 17 deletions src/MinFraud/ReportTransaction.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,11 @@ public function __construct(
* @param array $values An array of transaction parameters. The keys are the same
* as the JSON keys. You may use either this or the named
* arguments, but not both.
* @param string $ipAddress Required. The IP address of the customer placing the
* @param string $ipAddress Optional. The IP address of the customer placing the
* order. This should be passed as a string like
* "44.55.66.77" or "2001:db8::2:1".
* "44.55.66.77" or "2001:db8::2:1". This field is not
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also on me, but these "field" uses probably should all be "argument". It might be better for us to just do that in a separate PR though as I suspect it is endemic.

* required if you provide at least one of the transaction's
* `maxmindId`, `minfraudId`, or `transactionId`.
* @param string $tag Required. A string indicating the likelihood that a
* transaction may be fraudulent. Possible values:
* not_fraud, suspected_fraud, spam_or_abuse, or
Expand All @@ -57,24 +59,28 @@ public function __construct(
* processor indicating the reason for the chargeback.
* @param string $maxmindId Optional. A unique eight character string identifying
* a minFraud Standard or Premium request. These IDs are
* returned in the maxmindID field of a response for a
* returned in the `maxmindID` field of a response for a
* successful minFraud request. This field is not
* required, but you are encouraged to provide it, if
* possible.
* required if you provide at least one of the transaction's
* `ipAddress`, `minfraudId`, or `transactionId`. You are
* encouraged to provide it, if possible.
* @param string $minfraudId Optional. A UUID that identifies a minFraud Score,
* minFraud Insights, or minFraud Factors request. This
* ID is returned at /id in the response. This field is
* not required, but you are encouraged to provide it if
* the request was made to one of these services.
* not required if you provide at least one of the transaction's
* `ipAddress`, `maxmindId`, or `transactionId`. You are
* encouraged to provide it if the request was made to one of
* these services.
* @param string $notes Optional. Your notes on the fraud tag associated with
* the transaction. We manually review many reported
* transactions to improve our scoring for you so any
* additional details to help us understand context are
* helpful.
* @param string $transactionId Optional. The transaction ID you originally passed to
* minFraud. This field is not required, but you are
* encouraged to provide it or the transaction's
* maxmind_id or minfraud_id.
* minFraud. This field is not required if you provide at
* least one of the transaction's `ipAddress`, `maxmindId`, or
* `minfraudId`. You are encouraged to provide it or the
* transaction's `maxmindId` or `minfraudId`.
*
* @throws InvalidInputException when the request has missing or invalid
* data
Expand Down Expand Up @@ -120,14 +126,12 @@ public function report(
$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) {
Expand Down Expand Up @@ -166,6 +170,18 @@ public function report(
$values['transaction_id'] = $transactionId;
}

// One of these fields is required so we always throw an exception if one is not set
if (($ipAddress === null || $ipAddress === '')
&& ($minfraudId === null || $minfraudId === '')
&& ($maxmindId === null || $maxmindId === '')
&& ($transactionId === null || $transactionId === '')
) {
throw new InvalidInputException(
'The user must pass at least one of the following: ' .
'ipAddress, minfraudId, maxmindId, transactionId.'
);
}

$url = self::$basePath . 'transactions/report';
$this->client->post('ReportTransaction', $url, $values);
}
Expand Down
35 changes: 32 additions & 3 deletions tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,42 @@ public function testRequestsWithNulls(): void
);
}

public function testRequiredFields(): void
{
$this->expectNotToPerformAssertions();

$req = [
'ip_address' => '1.1.1.1',
'tag' => 'not_fraud',
];
$this->createReportTransactionRequest($req, 1)->report($req);

$req = [
'maxmind_id' => '12345678',
'tag' => 'not_fraud',
];
$this->createReportTransactionRequest($req, 1)->report($req);

$req = [
'minfraud_id' => '58fa38d8-4b87-458b-a22b-f00eda1aa20d',
'tag' => 'not_fraud',
];
$this->createReportTransactionRequest($req, 1)->report($req);

$req = [
'tag' => 'not_fraud',
'transaction_id' => 'abc123',
];
$this->createReportTransactionRequest($req, 1)->report($req);
}

/**
* @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,
Expand All @@ -82,7 +111,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,
Expand All @@ -94,7 +123,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' => [
Expand Down