Enable checked-exception analysis and fix input validation failures

CHANGELOG.md

@@ -1,6 +1,22 @@
 CHANGELOG
 =========
 
+3.8.0
+------------------
+
+* `with()` now rejects non-array sections and shopping cart items with
+  `InvalidInputException`, including when input validation is disabled.
+* Custom input validation now rejects integer keys and array or object values
+  with `InvalidInputException` instead of a type error or conversion warning.
+  When validation is disabled, these values pass through unchanged.
+* When input validation is disabled, billing, shipping, and credit card
+  country fields no longer fail in string validators. Billing and shipping
+  region and phone country code fields, and credit card bank phone country
+  codes, also pass through unchanged.
+* The PHPDoc for the `with()` and `with*()` methods of `MaxMind\MinFraud` now
+  lists the `InvalidInputException` they throw when input validation is
+  enabled.
+
 3.7.0 (2026-07-21)
 ------------------
 

CLAUDE.md

@@ -240,7 +240,7 @@ When adding a new input field to a `->with*()` method:
    return $new;
    ```
 
-5. **Update PHPDoc** with full documentation
+5. **Update PHPDoc**, including `@throws InvalidInputException` on validation methods and their callers.
 6. **Add tests** for the new field
 7. **Update CHANGELOG.md**
 
@@ -289,6 +289,9 @@ When adding input validation:
 
 1. **Create a validation method** following the pattern:
    ```php
+   /**
+    * @throws InvalidInputException if validation is enabled and the value is invalid
+    */
    private function verifyFieldName(string $value): void
    {
        if (!preg_match('/pattern/', $value)) {

composer.json

@@ -22,10 +22,10 @@
     "geoip2/geoip2": "^v3.4.0"
   },
   "require-dev": {
-    "friendsofphp/php-cs-fixer": "3.*",
+    "friendsofphp/php-cs-fixer": "^3.95",
     "phpunit/phpunit": "^10.0",
-    "squizlabs/php_codesniffer": "*",
-    "phpstan/phpstan": "*"
+    "squizlabs/php_codesniffer": "^4.0",
+    "phpstan/phpstan": "^2.2"
   },
   "suggest": {
     "ext-intl": "Enables improved email address IDN normalization"

phpstan.neon

@@ -3,3 +3,16 @@ parameters:
     paths:
         - src
         - tests
+    exceptions:
+        # These classes signal programmer errors, so callers need not declare them.
+        uncheckedExceptionClasses:
+            - Error
+            - LogicException
+        check:
+            missingCheckedExceptionInThrows: true
+    ignoreErrors:
+        # PHPUnit handles exceptions from test methods and their helpers.
+        -
+            identifier: missingType.checkedException
+            path: tests/*
+            reportUnmatched: false

src/MinFraud/ReportTransaction.php

@@ -29,6 +29,9 @@ class ReportTransaction extends ServiceClient
      *   to the `with*()` methods are validated. It is recommended that you
      *   leave validation on while developing and only (optionally) disable it
      *   before deployment.
+     *
+     * @throws \RuntimeException   with older web-service-common releases, if HTTP client setup fails
+     * @throws WebServiceException if HTTP client setup fails
      */
     public function __construct(
         int $accountId,
@@ -90,9 +93,8 @@ public function __construct(
      *                                 other reason, e.g., invalid JSON in the
      *                                 POST.
      * @throws HttpException           when an unexpected HTTP error occurs
-     * @throws WebServiceException     when some other error occurs. This also
-     *                                 serves as the base class for the above
-     *                                 exceptions.
+     * @throws \RuntimeException       with older web-service-common releases, if cURL setup fails
+     * @throws WebServiceException     when another web service error occurs
      */
     public function report(
         array $values = [],

src/MinFraud/ServiceClient.php

@@ -5,6 +5,7 @@
 namespace MaxMind\MinFraud;
 
 use MaxMind\Exception\InvalidInputException;
+use MaxMind\Exception\WebServiceException;
 use MaxMind\WebService\Client;
 
 abstract class ServiceClient
@@ -35,6 +36,9 @@ abstract class ServiceClient
      * @param int                  $accountId  your account ID
      * @param string               $licenseKey your license key
      * @param array<string, mixed> $options    options for the client
+     *
+     * @throws \RuntimeException   with older web-service-common releases, if HTTP client setup fails
+     * @throws WebServiceException if HTTP client setup fails
      */
     public function __construct(
         int $accountId,
@@ -60,6 +64,9 @@ protected function userAgent(): string
         return 'minFraud-API/' . self::VERSION;
     }
 
+    /**
+     * @throws InvalidInputException if input validation is enabled
+     */
     protected function maybeThrowInvalidInputException(string $msg): void
     {
         if ($this->validateInput) {
@@ -73,6 +80,9 @@ protected function maybeThrowInvalidInputException(string $msg): void
      * @param array<string, mixed> $array the parent array
      * @param string               $key   the key to remove
      * @param list<string>         $types the expected types
+     *
+     * @throws InvalidInputException if the value has an unexpected type and
+     *                               input validation is enabled
      */
     protected function remove(array &$array, string $key, array $types = ['string']): mixed
     {
@@ -94,6 +104,9 @@ protected function remove(array &$array, string $key, array $types = ['string'])
 
     /**
      * @param array<mixed> $values
+     *
+     * @throws InvalidInputException if the array has unknown keys and input
+     *                               validation is enabled
      */
     protected function verifyEmpty(array $values): void
     {

tests/MaxMind/Test/MinFraud/ReportTransaction/ReportTransactionTest.php

@@ -137,6 +137,18 @@ public static function requestsMissingRequiredFields(): array
         ];
     }
 
+    public function testValuesWithNamedArgs(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('not both');
+
+        $req = Data::minimalRequest();
+        $this->createReportTransactionRequest(
+            $req,
+            0
+        )->report($req, notes: 'some notes');
+    }
+
     public function testUnknownKey(): void
     {
         $this->expectException(InvalidInputException::class);

tests/MaxMind/Test/MinFraudTest.php

@@ -16,6 +16,98 @@
  */
 class MinFraudTest extends ServiceClientTester
 {
+    /**
+     * @dataProvider invalidRequestStructures
+     *
+     * @param array<string, mixed> $values
+     */
+    public function testInvalidRequestStructure(array $values, bool $validate): void
+    {
+        $client = new MinFraud(1, 'key', ['validateInput' => $validate]);
+        $this->expectException(InvalidInputException::class);
+        $this->expectExceptionMessage('must be an array');
+        $client->with($values);
+    }
+
+    /**
+     * @return array<array{array<string, mixed>, bool}>
+     */
+    public static function invalidRequestStructures(): array
+    {
+        $cases = [];
+        foreach ([true, false] as $validate) {
+            foreach ([
+                ['device' => null],
+                ['device' => 'x'],
+                ['shopping_cart' => null],
+                ['shopping_cart' => ['x']],
+            ] as $values) {
+                $cases[] = [$values, $validate];
+            }
+        }
+
+        return $cases;
+    }
+
+    /**
+     * @dataProvider invalidCustomInputs
+     *
+     * @param array<mixed> $values
+     */
+    public function testInvalidCustomInput(array $values): void
+    {
+        $client = new MinFraud(1, 'key');
+        $this->expectException(InvalidInputException::class);
+        $client->withCustomInputs($values);
+    }
+
+    /**
+     * @dataProvider invalidCustomInputs
+     *
+     * @param array<mixed> $values
+     */
+    public function testCustomInputsWithoutValidation(array $values): void
+    {
+        $client = new MinFraud(1, 'key', ['validateInput' => false]);
+        $result = $client->withCustomInputs($values);
+        $this->assertSame($values, $result->jsonSerialize()['content']['custom_inputs']);
+    }
+
+    /**
+     * @return array<array{array<mixed>}>
+     */
+    public static function invalidCustomInputs(): array
+    {
+        return [[['value']], [['a' => new \stdClass()]], [['a' => ['x']]]];
+    }
+
+    /**
+     * @dataProvider unvalidatedAddressFields
+     */
+    public function testAddressFieldWithoutValidation(string $method, string $section, string $field): void
+    {
+        $client = new MinFraud(1, 'key', ['validateInput' => false]);
+        $result = $client->{$method}([$field => 12]);
+        $this->assertSame(12, $result->jsonSerialize()['content'][$section][$field]);
+    }
+
+    /**
+     * @return array<array{string, string, string}>
+     */
+    public static function unvalidatedAddressFields(): array
+    {
+        return [
+            ['withBilling', 'billing', 'country'],
+            ['withBilling', 'billing', 'region'],
+            ['withBilling', 'billing', 'phone_country_code'],
+            ['withShipping', 'shipping', 'country'],
+            ['withShipping', 'shipping', 'region'],
+            ['withShipping', 'shipping', 'phone_country_code'],
+            ['withCreditCard', 'credit_card', 'country'],
+            ['withCreditCard', 'credit_card', 'bank_phone_country_code'],
+        ];
+    }
+
     public function testMinFraud(): void
     {
         $minFraud = new MinFraud(0, '', ['hashEmail' => true, 'locales' => ['en', 'fr']]);
@@ -442,6 +534,7 @@ public function testUnknownKeys(string $method): void
     public static function withMethods(): array
     {
         return [
+            ['withDevice'],
             ['withEvent'],
             ['withAccount'],
             ['withEmail'],
@@ -454,6 +547,39 @@ public static function withMethods(): array
         ];
     }
 
+    /**
+     * @dataProvider withNamedArguments
+     */
+    public function testValuesWithNamedArgs(string $method, string $parameter): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('not both');
+
+        $this->createMinFraudRequestWithFullResponse(
+            'insights',
+            0
+        )->{$method}(['unknown' => 'some value'], ...[$parameter => 'value']);
+    }
+
+    /**
+     * @return array<array{string, string}>
+     */
+    public static function withNamedArguments(): array
+    {
+        return [
+            ['withDevice', 'userAgent'],
+            ['withEvent', 'transactionId'],
+            ['withAccount', 'userId'],
+            ['withEmail', 'domain'],
+            ['withBilling', 'country'],
+            ['withShipping', 'country'],
+            ['withPayment', 'processor'],
+            ['withCreditCard', 'country'],
+            ['withOrder', 'currency'],
+            ['withShoppingCartItem', 'itemId'],
+        ];
+    }
+
     /**
      * @dataProvider badMd5s
      */