AssociativeArray::$allowAdditional now defaults to TRUE

Author: PhrozenByte

README.md

@@ -33,7 +33,7 @@ All options do the same, the only difference is that the static class and trait
 
 The `AssociativeArray` constraint asserts that a value is an associative array matching a given structure and that the array's items pass other constraints.
 
-Any native array and `ArrayAccess` object is considered an associative array, no matter which keys they use. However, the array's items are applied to the matching constraint (parameter `$consotraints`). By default, additional items will fail the constraint (parameter `$allowAdditional`, defaults to `false`). The same is true when items are missing (parameter `$allowMissing`, defaults to `false`). The expected keys and constraints to apply, as well as whether additional and/or missing items should fail the constraint, are passed in the constructor.
+Any native array and `ArrayAccess` object is considered an associative array, no matter which keys they use. However, the array's items are applied to the matching constraint (parameter `$consotraints`). By default, missing items will fail the constraint (parameter `$allowMissing`, defaults to `false`). Additional items will be ignored by default (parameter `$allowAdditional`, defaults to `true`). If you want the constraint to fail when additional items exist, set this option to `true`, however, please note that this works for native arrays only. The expected keys and constraints to apply, as well as whether missing and/or additional items should fail the constraint, are passed in the constructor.
 
 **Usage:**
 
@@ -42,16 +42,16 @@ Any native array and `ArrayAccess` object is considered an associative array, no
 self::assertAssociativeArray(
     array $constraints,            // an associative array with the expected keys and constraints to apply
     array|ArrayAccess $array,      // the associative array to check
-    bool $allowAdditional = false, // whether additional items should fail the constraint
     bool $allowMissing = false,    // whether missing items should fail the constraint
+    bool $allowAdditional = true,  // whether additional items should fail the constraint
     string $message = ''           // additional information about the test
 );
 
 // using new instance of `\PhrozenByte\PHPUnitArrayAsserts\Constraint\AssociativeArray`
 new AssociativeArray(
     array $constraints,
-    bool $allowAdditional = false,
-    bool $allowMissing = false
+    bool $allowMissing = false,
+    bool $allowAdditional = true
 );
 ```
 
@@ -236,13 +236,13 @@ class MyTest extends TestCase
         $this->assertAssociativeArray([
             'id'      => $this->isType(IsType::TYPE_INT),
             'name'    => $this->identicalTo('Arthur Dent'),
-            'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ], true)
+            'options' => $this->associativeArray([ 'panic' => $this->isType(IsType::TYPE_BOOL) ])
         ], $responseData['users'][0]);
     }
 
     public function testWithoutPHPUnitArrayAsserts(): void
     {
-        // 18 lines of pretty repetitive code to check the API response *without* PHPUnitArrayAsserts
+        // 17 lines of pretty repetitive code to check the API response *without* PHPUnitArrayAsserts
 
         // implement your test, the result is stored in $responseData
 
@@ -261,7 +261,6 @@ class MyTest extends TestCase
         $this->assertGreaterThanOrEqual(1, count($responseData['users'])); // won't work for Traversable
 
         $userData = $responseData['users'][0]; // we can't really rely on the existence of key "0" here :/
-        $this->assertEmpty(array_diff_key($userData, [ 'id' => true, 'name' => true, 'options' => true ]));
 
         $this->assertArrayHasKey('id', $userData);
         $this->assertIsInt($userData['id']);
@@ -273,7 +272,7 @@ class MyTest extends TestCase
         $this->assertIsArray($userData['options']);
 
         $this->assertArrayHasKey('panic', $userData['options']);
-        $this->assertIsBool($userData['options']['bool']);
+        $this->assertIsBool($userData['options']['panic']);
     }
 }
 ```

src/ArrayAssertsTrait.php

@@ -39,8 +39,9 @@ trait ArrayAssertsTrait
      *
      * @param Constraint[]      $constraints     an associative array with the expected keys and constraints to apply
      * @param array|ArrayAccess $array           the associative array to check
-     * @param bool              $allowAdditional whether additional items should fail the constraint (defaults to FALSE)
      * @param bool              $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
+     * @param bool              $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
+     *                                           this option works for native arrays only
      * @param string            $message         additional information about the test
      *
      * @throws ExpectationFailedException
@@ -50,8 +51,8 @@ trait ArrayAssertsTrait
     public static function assertAssociativeArray(
         array $constraints,
         $array,
-        bool $allowAdditional = false,
         bool $allowMissing = false,
+        bool $allowAdditional = true,
         string $message = ''
     ): void {
         $isNoConstraint = static function ($constraint): bool { return !($constraint instanceof Constraint); };
@@ -63,27 +64,32 @@ public static function assertAssociativeArray(
             throw InvalidArgumentException::create(2, 'array or ArrayAccess');
         }
 
-        $constraint = new AssociativeArray($constraints, $allowAdditional, $allowMissing);
+        if (!is_array($array) && !$allowAdditional) {
+            throw InvalidArgumentException::create(2, 'array when argument #4 is set true');
+        }
+
+        $constraint = new AssociativeArray($constraints, $allowMissing, $allowAdditional);
         PHPUnitAssert::assertThat($array, $constraint, $message);
     }
 
     /**
      * Returns a new instance of the AssociativeArray constraint.
      *
      * @param Constraint[] $constraints     an associative array with the expected keys and constraints to apply
-     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to FALSE)
      * @param bool         $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
+     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
+     *                                      this option works for native arrays only
      *
      * @return AssociativeArray
      *
      * @throws Exception
      */
     public static function associativeArray(
         array $constraints,
-        bool $allowAdditional = false,
-        bool $allowMissing = false
+        bool $allowMissing = false,
+        bool $allowAdditional = true
     ): AssociativeArray {
-        return new AssociativeArray($constraints, $allowAdditional, $allowMissing);
+        return new AssociativeArray($constraints, $allowMissing, $allowAdditional);
     }
 
     /**

src/Constraint/AssociativeArray.php

@@ -43,19 +43,20 @@ class AssociativeArray extends Constraint
     protected $constraints = [];
 
     /** @var bool */
-    protected $allowAdditional;
+    protected $allowMissing;
 
     /** @var bool */
-    protected $allowMissing;
+    protected $allowAdditional;
 
     /**
      * AssociativeArray constructor.
      *
      * @param Constraint[] $constraints     an associative array with the expected keys and constraints to apply
-     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to FALSE)
      * @param bool         $allowMissing    whether missing items should fail the constraint (defaults to FALSE)
+     * @param bool         $allowAdditional whether additional items should fail the constraint (defaults to TRUE);
+     *                                      this option works for native arrays only
      */
-    public function __construct(array $constraints, bool $allowAdditional = false, bool $allowMissing = false)
+    public function __construct(array $constraints, bool $allowMissing = false, bool $allowAdditional = true)
     {
         foreach ($constraints as $key => $constraint) {
             if (!($constraint instanceof Constraint)) {
@@ -66,8 +67,8 @@ public function __construct(array $constraints, bool $allowAdditional = false, b
             $this->constraints[$key] = $constraint;
         }
 
-        $this->allowAdditional = $allowAdditional;
         $this->allowMissing = $allowMissing;
+        $this->allowAdditional = $allowAdditional;
     }
 
     /**
@@ -82,7 +83,7 @@ public function toString(): string
         }
 
         return 'is an associative array that '
-            . implode(!$this->allowMissing ? ' and ' : ' or ', $constraintDescriptions)
+            . implode(!$this->allowMissing ? ' and ' : ' and/or ', $constraintDescriptions)
             . ($this->allowAdditional ? ' or any other item' : '');
     }
 
@@ -104,7 +105,7 @@ protected function matches($other): bool
             }
         }
 
-        if (!$this->allowAdditional) {
+        if (is_array($other) && !$this->allowAdditional) {
             return !array_diff_key($other, $this->constraints);
         }
 
@@ -165,9 +166,9 @@ protected function additionalFailureDescription($other): string
 
         $output = $table->getTable();
         $output .= sprintf(
-            "[%s] Allow additional; [%s] Allow missing\n",
-            $this->allowAdditional ? 'x' : ' ',
-            $this->allowMissing ? 'x' : ' '
+            "[%s] Allow missing; [%s] Allow additional\n",
+            $this->allowMissing ? 'x' : ' ',
+            $this->allowAdditional ? 'x' : ' '
         );
 
         return $output;