alezhu/phpunit-array-contains-asserts

Provides PHPUnit assertions to test array contains data or structure

13.0.0 2026-08-08 21:26 UTC

Requires

• php: ^8.3

Requires (Dev)

• phpunit/phpunit: ^12 || ^13

MIT

• Alexandr Zhuravlev

• php
• phpunit
• phpunit-extension
• phpunit-assertions

Published on Packagist.org on 2026-08-08 21:26 UTC

README

Provides PHPUnit assertions to test when array-like data contains expected data with expected structure.

Supported PHPUnit Versions & Status

PHPUnit Version	Latest Package Release	Build Status	Coverage	PHP Version
PHPUnit 13
PHPUnit 12

Note

For older PHPUnit versions, please use the corresponding branch:

• For PHPUnit 11 and PHPUnit 10: Use the PHPUnit_11 branch.
• For PHPUnit 9: Use the PHPUnit_9 branch.
• For PHPUnit 8: Use the PHPUnit_8 branch.

Table of contents:

1. Install
2. Usage
   1. Constraint ArrayContains
   2. Constraint ArrayContainsOnly

Install

PHPUnit arrayContains asserts is available on Packagist.org and can be installed using Composer:

composer require --dev alezhu/phpunit-array-contains-asserts

Usage

There are three (basically equivalent) options to use PHPUnitArrayAssertions:

• By using the static class Alezhu\PHPUnitArrayContainsAsserts\Assert
• By using the trait Alezhu\PHPUnitArrayContainsAsserts\ArrayContainsTrait in your test case
• By creating new constraint instances ( Alezhu\PHPUnitArrayContainsAsserts\Constraint\…)

All options do the same, the only difference is that the static class and trait both throw class Alezhu\PHPUnitArrayContainsAsserts\Exception\InvalidArgumentTypeException ( or PHPUnit\Framework\InvalidArgumentException for PHPUnit 9 and 8) exceptions for invalid parameters. Creating new constraint instances is useful for advanced assertions, e.g. together with PHPUnit\Framework\Constraint\LogicalAnd.

Constraint ArrayContains

The ArrayContains constraint asserts that an array contains all expected values (for non-associative arrays) or all expected keys with expected values (for associative arrays).

Expected values can be set directly or via another PHPUnit constraints (PHPUnit\Framework\Constraint\...).

Expected and actual data can be array or iterator or inherit ArrayObject or implements ArrayAccess+Countable interfaces.

Expected and actual data must have same associative kind.

Usage:

use Alezhu\PHPUnitArrayContainsAsserts\Assert;
use PHPUnit\Framework\Assert as PHPUnitAssert;

//Passed
Assert::assertArrayContains(
    [
        "foo" => PHPUnitAssert::isString(), 
        "baz" => 1
    ], 
    [
        "foo" => "value",
        "bar" => true, 
        "baz" => 1
    ]
); 
//Not Passed
Assert::assertArrayContains(
    [
        "foo" => PHPUnitAssert::isString(), 
        "baz" => 1
    ], 
    [
        "foo" => "bar", 
    ]
); 

Constraint ArrayContainsOnly

The ArrayContainsOnly constraint asserts that an array contains only all expected values (for non-associative arrays) or only all expected keys with expected values (for associative arrays).

Expected values can be set directly or via another PHPUnit constraints (PHPUnit\Framework\Constraint\...).

Expected and actual data can be array or iterator or inherit ArrayObject or implements ArrayAccess+Countable interfaces.

Expected and actual data must have same associative kind.

Usage:

use Alezhu\PHPUnitArrayContainsAsserts\Assert;
use PHPUnit\Framework\Assert as PHPUnitAssert;

//Passed
Assert::assertArrayContainsOnly(
    [
        "foo" => PHPUnitAssert::isString(), 
        "baz" => 1
    ], 
    [
        "foo" => "value",
        "baz" => 1
    ]
); 
//Not Passed
Assert::assertArrayContainsOnly(
    [
        "foo" => PHPUnitAssert::isString(), 
        "baz" => 1
    ], 
    [
        "foo" => "bar",
        "bar" => true, 
        "baz" => 1         
    ]
);