SequentialArray: Add $ignoreKeys option

Author: PhrozenByte

README.md

@@ -170,7 +170,7 @@ $this->assertArrayHasKeyWith('answer', 42, $data);
 
 The [`SequentialArray` constraint](https://github.com/PhrozenByte/phpunit-array-asserts/blob/master/src/Constraint/SequentialArray.php) asserts that a value is like a sequential array, has a minimum and/or maximum number of items, and that all items pass another constraint.
 
-Sequential arrays are defined as ordered lists with incrementing numeric keys starting from zero. This is especially true for native sequential arrays like `[ "foo", "bar" ]`. Empty arrays are considered valid, too. `Traversable` objects must have sequential keys to be considered valid. The expected minimum (parameter `$minItems`, defaults to `0`) and/or maximum (parameter `$maxItems`, defaults to `null`, meaning infinite) number of items, and the constraint to apply all items to (optional parameter `$constraint`), are passed in the constructor. The constraint can either be an arbitrary `Constraint` instance (e.g. `PHPUnit\Framework\Constraint\StringContains`), or any static value, requiring an exact match of the value.
+Sequential arrays are defined as ordered lists with incrementing numeric keys starting from zero. This is especially true for native sequential arrays like `[ "foo", "bar" ]`. Empty arrays are considered valid, too. `Traversable` objects must have sequential keys to be considered valid. The expected minimum (parameter `$minItems`, defaults to `0`) and/or maximum (parameter `$maxItems`, defaults to `null`, meaning infinite) number of items, and the constraint to apply all items to (optional parameter `$constraint`), are passed in the constructor. The constraint can either be an arbitrary `Constraint` instance (e.g. `PHPUnit\Framework\Constraint\StringContains`), or any static value, requiring an exact match of the value. Requiring sequential keys can be disabled by setting parameter `$ignoreKeys` to `true` (defaults to `false`), causing the constraint to check just for the required number of items and whether they match the given constraint.
 
 This constraint will fully traverse any `Traversable` object given. This also means that any `Generator` will be fully exhausted. If possible, it will try to restore an `Iterator`'s pointer to its previous state.
 
@@ -185,14 +185,16 @@ ArrayAssertsTrait::assertSequentialArray(
     int $minItems,                       // required minimum number of items
     int $maxItems = null,                // required maximum number of items (pass null for infinite)
     Constraint|mixed $constraint = null, // optional constraint to apply all items to
+    bool $ignoreKeys = false,            // whether to ignore non-sequential keys
     string $message = ''                 // additional information about the test
 );
 
 // using new instance of `\PhrozenByte\PHPUnitArrayAsserts\Constraint\SequentialArray`
 new SequentialArray(
     int $minItems = 0,
     int $maxItems = null,
-    Constraint|mixed $constraint = null
+    Constraint|mixed $constraint = null,
+    bool $ignoreKeys = false
 );
 ```
 

src/ArrayAssertsTrait.php

@@ -148,6 +148,7 @@ public static function arrayHasKeyWith($key, $constraint): ArrayHasKeyWith
      * @param int                   $minItems   required minimum number of items, defaults to 0
      * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
      * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param bool                  $ignoreKeys whether to ignore non-sequential keys (defaults to FALSE)
      * @param string                $message    additional information about the test
      *
      * @throws ExpectationFailedException
@@ -159,13 +160,14 @@ public static function assertSequentialArray(
         int $minItems,
         int $maxItems = null,
         $constraint = null,
+        bool $ignoreKeys = false,
         string $message = ''
     ): void {
         if (!(is_array($array) || ($array instanceof Traversable))) {
             throw InvalidArgumentException::create(1, 'array or Traversable');
         }
 
-        $itemConstraint = new SequentialArray($minItems, $maxItems, $constraint);
+        $itemConstraint = new SequentialArray($minItems, $maxItems, $constraint, $ignoreKeys);
         PHPUnitAssert::assertThat($array, $itemConstraint, $message);
     }
 
@@ -175,14 +177,19 @@ public static function assertSequentialArray(
      * @param int                   $minItems   required minimum number of items, defaults to 0
      * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
      * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param bool                  $ignoreKeys whether to ignore non-sequential keys (defaults to FALSE)
      *
      * @return SequentialArray
      *
      * @throws InvalidArgumentException
      */
-    public static function sequentialArray(int $minItems, int $maxItems = null, $constraint = null): SequentialArray
-    {
-        return new SequentialArray($minItems, $maxItems, $constraint);
+    public static function sequentialArray(
+        int $minItems,
+        int $maxItems = null,
+        $constraint = null,
+        bool $ignoreKeys = false
+    ): SequentialArray {
+        return new SequentialArray($minItems, $maxItems, $constraint, $ignoreKeys);
     }
 
     /**

src/Constraint/SequentialArray.php

@@ -39,16 +39,19 @@
  * keys starting from zero. This is especially true for native sequential
  * arrays like `[ "foo", "bar" ]`. Empty arrays are considered valid, too.
  * Traversable objects must have sequential keys to be considered valid.
+ * Requiring sequential keys can be disabled, causing this constraint to just
+ * check for the required number of items an whether all of its items are
+ * considered valid.
  *
  * This constraint will fully traverse any Traversable object given. This also
  * means that any Generator will be fully exhausted. If possible, it will try
  * to restore an Iterator's pointer to its previous state.
  *
  * The expected minimum and/or maximum number of items, as well as the
- * constraint to apply all items to, are passed in the constructor. The
- * constraint can either be an arbitrary `Constraint` instance (e.g.
- * `PHPUnit\Framework\Constraint\StringContains`), or any static value,
- * requiring an exact match of the value.
+ * constraint to apply all items to and the option to disable key checking, are
+ * passed in the constructor. The constraint can either be an arbitrary
+ * `Constraint` instance (e.g. `PHPUnit\Framework\Constraint\StringContains`),
+ * or any static value, requiring an exact match of the value.
  */
 class SequentialArray extends Constraint
 {
@@ -61,16 +64,20 @@ class SequentialArray extends Constraint
     /** @var Constraint|null */
     protected $constraint;
 
+    /** @var bool */
+    protected $ignoreKeys;
+
     /**
      * SequentialArray constructor.
      *
      * @param int                   $minItems   required minimum number of items, defaults to 0
      * @param int|null              $maxItems   required maximum number of items, defaults to NULL (infinite)
      * @param Constraint|mixed|null $constraint optional constraint to apply all items to (defaults to NULL)
+     * @param bool                  $ignoreKeys whether to ignore non-sequential keys (defaults to FALSE)
      *
      * @throws InvalidArgumentException
      */
-    public function __construct(int $minItems = 0, int $maxItems = null, $constraint = null)
+    public function __construct(int $minItems = 0, int $maxItems = null, $constraint = null, bool $ignoreKeys = false)
     {
         if ($minItems < 0) {
             throw InvalidArgumentException::create(1, 'non-negative integer');
@@ -86,6 +93,7 @@ public function __construct(int $minItems = 0, int $maxItems = null, $constraint
 
         $this->minItems = $minItems;
         $this->maxItems = $maxItems;
+        $this->ignoreKeys = $ignoreKeys;
 
         if ($constraint !== null) {
             $this->constraint = !($constraint instanceof Constraint) ? new IsEqual($constraint) : $constraint;
@@ -103,11 +111,12 @@ public function toString(): string
             return 'is an empty array';
         }
 
+        $description = !$this->ignoreKeys ? 'sequential array' : 'list array';
         if (($this->minItems <= 1) && ($this->maxItems === null)) {
-            $text = 'is a' . (($this->minItems > 0) ? ' non-empty' : '') . ' sequential array';
+            $text = 'is a' . (($this->minItems > 0) ? ' non-empty' : '') . ' ' . $description;
             $text .= ($this->constraint !== null) ? ' whose items match' : '';
         } else {
-            $text = 'is a sequential array';
+            $text = 'is a ' . $description;
             if ($this->minItems && $this->maxItems) {
                 if ($this->minItems === $this->maxItems) {
                     $text .= ' with exactly ' . $this->minItems . ' ' . (($this->minItems > 1) ? 'items' : 'item');
@@ -207,7 +216,11 @@ protected function inspectData($other): array
     {
         if (is_array($other)) {
             $itemCount = count($other);
-            $valid = (($itemCount === 0) || (isset($other[0]) && ($other === array_values($other))));
+
+            $valid = true;
+            if (($itemCount > 0) && !$this->ignoreKeys) {
+                $valid = (isset($other[0]) && ($other === array_values($other)));
+            }
 
             $itemsValid = true;
             if ($valid && ($this->constraint !== null)) {
@@ -250,7 +263,7 @@ protected function inspectData($other): array
             $itemCount = 0;
             $itemsValid = true;
             foreach ($other as $key => $item) {
-                if ($key !== $itemCount++) {
+                if (($key !== $itemCount++) && !$this->ignoreKeys) {
                     $valid = false;
                 }
 

tests/Unit/ArrayAssertsTraitTest.php

@@ -260,26 +260,21 @@ public function dataProviderArrayHasKeyWithFail(): array
     /**
      * @dataProvider dataProviderSequentialArray
      *
-     * @param int               $minItems
-     * @param int|null          $maxItems
-     * @param Constraint|null   $constraint
+     * @param int             $minItems
+     * @param int|null        $maxItems
+     * @param Constraint|null $constraint
+     * @param bool            $ignoreKeys
      */
     public function testSequentialArray(
         int $minItems,
         ?int $maxItems,
-        ?Constraint $constraint
+        ?Constraint $constraint,
+        bool $ignoreKeys
     ): void {
-        $this->mockConstraintInstance(
-            SequentialArray::class,
-            [ $minItems, $maxItems, $constraint ]
-        );
+        $constraintArgs = [ $minItems, $maxItems, $constraint, $ignoreKeys ];
+        $this->mockConstraintInstance(SequentialArray::class, $constraintArgs);
 
-        $callableProxy = new CachedCallableProxy(
-            [ Assert::class, 'sequentialArray' ],
-            $minItems,
-            $maxItems,
-            $constraint
-        );
+        $callableProxy = new CachedCallableProxy([ Assert::class, 'sequentialArray' ], ...$constraintArgs);
 
         $this->assertCallableThrowsNot($callableProxy, InvalidArgumentException::class);
         $this->assertInstanceOf(SequentialArray::class, $callableProxy->getReturnValue());
@@ -291,22 +286,21 @@ public function testSequentialArray(
      * @param int               $minItems
      * @param int|null          $maxItems
      * @param Constraint|null   $constraint
+     * @param bool              $ignoreKeys
      * @param array|Traversable $array
      */
     public function testAssertSequentialArray(
         int $minItems,
         ?int $maxItems,
         ?Constraint $constraint,
+        bool $ignoreKeys,
         $array
     ): void {
-        $this->mockConstraintInstance(
-            SequentialArray::class,
-            [ $minItems, $maxItems, $constraint ],
-            [ $array, '' ]
-        );
+        $constraintArgs = [ $minItems, $maxItems, $constraint, $ignoreKeys ];
+        $this->mockConstraintInstance(SequentialArray::class, $constraintArgs, [ $array, '' ]);
 
         $this->assertCallableThrowsNot(
-            $this->callableProxy([ Assert::class, 'assertSequentialArray' ], $array, $minItems, $maxItems, $constraint),
+            $this->callableProxy([ Assert::class, 'assertSequentialArray' ], $array, ...$constraintArgs),
             InvalidArgumentException::class
         );
     }
@@ -325,6 +319,7 @@ public function dataProviderSequentialArray(): array
      * @param int               $minItems
      * @param int|null          $maxItems
      * @param Constraint|null   $constraint
+     * @param bool              $ignoreKeys
      * @param array|Traversable $array
      * @param string            $expectedException
      * @param string            $expectedExceptionMessage
@@ -333,18 +328,16 @@ public function testAssertSequentialArrayFail(
         int $minItems,
         ?int $maxItems,
         ?Constraint $constraint,
+        bool $ignoreKeys,
         $array,
         string $expectedException,
         string $expectedExceptionMessage
     ): void {
-        $this->mockConstraintInstance(
-            SequentialArray::class,
-            [ $minItems, $maxItems, $constraint ],
-            [ $array, '' ]
-        );
+        $constraintArgs = [ $minItems, $maxItems, $constraint, $ignoreKeys ];
+        $this->mockConstraintInstance(SequentialArray::class, $constraintArgs, [ $array, '' ]);
 
         $this->assertCallableThrows(
-            $this->callableProxy([ Assert::class, 'assertSequentialArray' ], $array, $minItems, $maxItems, $constraint),
+            $this->callableProxy([ Assert::class, 'assertSequentialArray' ], $array, ...$constraintArgs),
             $expectedException,
             $expectedExceptionMessage
         );