3. Utilities

arrayValues()

Prerequisites for arrayValues()

Package	phptailors/phpunit-arrays: ^1.1 || ^2.1 || ^3.1 || ^4.1 || ^5.1
Trait	ArrayValuesTrait

Since versions *.1 (1.1, 2.1, 3.1, …) it’s possible to treat arrays nested somewhere within data structure same way as they are handled at the top level by constraint such as arrayValuesEqualTo(), arrayValuesIdenticalTo(). To achieve this, wrap nested arrays in your constraint specification ($expected) with arrayValues():

$expected = [
     'a' => 'A',
     'nested' => $this->arrayValues([
          'b' => 'B',
     ]),
];

When the above specification is used in arrayValuesEqualTo() / arrayValuesIdenticalTo(), it will match arrays, such as

$actual = [
      // ... other optional items at top-level
     'a' => 'A',
      // ... other optional items at top-level
     'nested' => [
          // ... other optional items in nested
          'b' => 'B',
          // ... other optional items in nested
     ],
      // ... other optional items at top-level
];

Without arrayValues([...]), the value under $actual['nested'] would be compared verbatim, that is only the exact array ['b' => 'B'] would match:

$actual = [
      // ... other optional items at top-level
     'a' => 'A',
      // ... other optional items at top-level
     'nested' => ['b' => 'B'], // other keys not allowed in nested array
      // ... other optional items at top-level
];

arrayValues() may be applied at any depth in the expectation array and may be used recursively

$expected = [
     'a' => [
         'b' => $this->arrayValues([
             // ...
         ])
     ],
     'c' => $this->arrayValues([
         'd' => $this->arrayValues([ /* ... */ ])
     ])
];

The utility may be used in array-related constraints, such as arrayValuesEqualTo() as well as other selection-based constraints (e.g. objectPropertiesEqualTo()). It may be mixed recursively with other selection-related utilities such as classProperties() or objectProperties().

classProperties()

Prerequisites for classProperties()

Package	phptailors/phpunit-arrays: ^1.1 || ^2.1 || ^3.1 || ^4.1 || ^5.1
Trait	ClassPropertiesTrait

Since versions *.1 (1.1, 2.1, 3.1, …) it’s possible to treat class names nested somewhere in data structure same way as they are handled at the top level by classPropertiesEqualTo() or classPropertiesIdenticalTo() constraint. To achieve this, wrap the specification of class properties nested somewhere in your expectation specs ($expected) with classProperties():

$expected = [
     'a' => 'A',
     'nested()' => $this->classProperties([
          'getMessage()' => 'File not found!',
     ])
];

For example, assuming that class Foo is defined as

class Foo {
     public static function nested(): \Exception
     {
         return new \Exception('File not found!');
     }
}

The above specification of $expected values will match classes, such as

class Bar {
       // ... other optional properties at top-level
      public static $a = 'A';
       // ... other optional properties at top-level
      public static $nested = Foo::class;
       // ... other optional properties at top-level
 };

when compared with classPropertiesEqualTo().

Without classProperties([...]), the value under $actual['nested()'] would be compared verbatim, that is only the exact array ['getMessage()' => 'File not found!"] would match.

classProperties() may be applied at any level and may be used recursively

$expected = [
     'a' => [
         'b' => $this->classProperties([
             // ...
         ])
     ],
     'c' => $this->classProperties([
         'd' => $this->classProperties([ /* ... */ ])
     ])
];

The utility may be used in class-properties-related constraints, such as classPropertiesEqualTo() as well as other selection-based constraints (e.g. objectPropertiesEqualTo()). It may be mixed recursively with other selection-related utilities such as arrayValues() or objectProperties().

objectProperties()

Prerequisites for objectProperties()

Package	phptailors/phpunit-arrays: ^1.1 || ^2.1 || ^3.1 || ^4.1 || ^5.1
Trait	ClassPropertiesTrait

Since versions *.1 (1.1, 2.1, 3.1, …) it’s possible to treat object references nested somewhere in data structure same way as they are handled at the top level by objectPropertiesEqualTo() or objectPropertiesIdenticalTo() constraint. To achieve this, wrap the specification of object properties nested somewhere in your expectation specs ($expected) with objectProperties():

$expected = [
     'a' => 'A',
     'nested()' => $this->objectProperties([
          'getMessage()' => 'File not found!',
     ])
];

For example, assuming that class Foo is defined as

class Foo {
     public function nested(): \Exception
     {
         return new \Exception('File not found!');
     }
}

The above specification of $expected values will match objects, such as

class Bar {
       // ... other optional properties at top-level
      public $a = 'A';
       // ... other optional properties at top-level
      public function nested(): Foo {
           return new Foo();
      }
       // ... other optional properties at top-level
 };

when compared with objectPropertiesEqualTo().

Without objectProperties([...]), the value under $actual['nested()'] would be compared verbatim, that is only the exact array ['getMessage()' => 'File not found!"] would match.

objectProperties() may be applied at any level and may be used recursively

$expected = [
     'a' => [
         'b' => $this->objectProperties([
             // ...
         ])
     ],
     'c' => $this->objectProperties([
         'd' => $this->objectProperties([ /* ... */ ])
     ])
];

The utility may be used in class-properties-related constraints, such as objectPropertiesEqualTo() as well as other selection-based constraints (e.g. objectPropertiesEqualTo()). It may be mixed recursively with other selection-related utilities such as arrayValues() or objectProperties().