PHPUnit Constraints

In PHPUnit, assertThat is a more flexible assertion method that allows you to use constraint objects to define complex or custom assertions.

The signature looks like:

$this->assertThat(mixed $value, PHPUnit\Framework\Constraint $constraint, string $message = '')

✅ Example: Using a built-in constraint

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Constraint\StringContains;

class MyTest extends TestCase
{
    public function testUsingAssertThat()
    {
        $value = "Hello World";

        // Equivalent to: $this->assertStringContainsString("Hello", $value);
        $this->assertThat($value, new StringContains("Hello"));
    }
}

✅ Common constraints you can use

use PHPUnit\Framework\Constraint\LogicalAnd;
use PHPUnit\Framework\Constraint\StringContains;

$this->assertThat(
    "Hello World",
    new LogicalAnd(
        new StringContains("Hello"),
        new StringContains("World")
    )
);

🧩 Custom constraint example

You can also make your own constraint by extending PHPUnit\Framework\Constraint\Constraint:

use PHPUnit\Framework\Constraint\Constraint;

class IsEven extends Constraint
{
    public function matches($other): bool
    {
        return $other % 2 === 0;
    }

    public function toString(): string
    {
        return 'is an even number';
    }
}

Usage:

$this->assertThat(4, new IsEven());

Constraints

🔤 Type and Equality Constraints

Constraint Class	Purpose	Equivalent Assertion
`IsType('type')`	Checks variable type (`string`, `int`, etc.)	`assertIsString()`, `assertIsInt()`, etc.
`IsEqual($value)`	Strict equality with value	`assertEquals()`
`IsIdentical($value)`	Identity (`===`) check	`assertSame()`
`IsNotEqual($value)`	Inequality	`assertNotEquals()`
`IsNotIdentical($value)`	Not identical (`!==`)	`assertNotSame()`

🔍 String Constraints

Constraint Class	Purpose	Equivalent Assertion
`StringContains($needle)`	Checks substring presence	`assertStringContainsString()`
`StringStartsWith($prefix)`	Checks if string starts with prefix	`assertStringStartsWith()`
`StringEndsWith($suffix)`	Checks if string ends with suffix	`assertStringEndsWith()`
`MatchesRegularExpression($pattern)`	Regex match	`assertMatchesRegularExpression()`

📏 Comparison Constraints

Constraint Class	Purpose	Equivalent Assertion
`GreaterThan($value)`	Greater than	`assertGreaterThan()`
`GreaterThanOrEqual($value)`	Greater than or equal	`assertGreaterThanOrEqual()`
`LessThan($value)`	Less than	`assertLessThan()`
`LessThanOrEqual($value)`	Less than or equal	`assertLessThanOrEqual()`

📚 Array and Count Constraints

Constraint Class	Purpose	Equivalent Assertion
`Count($expectedCount)`	Checks countable has expected size	`assertCount()`
`ArrayHasKey($key)`	Checks if array has key	`assertArrayHasKey()`
`ArraySubset($subset)`	Checks array contains a subset	(deprecated)

⚙️ Object & Class Constraints

Constraint Class	Purpose	Equivalent Assertion
`IsInstanceOf($className)`	Checks object instance	`assertInstanceOf()`
`ObjectHasAttribute($attrName)`	Checks object has attribute	`assertObjectHasAttribute()`
`ClassHasAttribute($attrName)`	Checks class has attribute	`assertClassHasAttribute()`
`ClassHasStaticAttribute($attrName)`	Checks static attribute exists	`assertClassHasStaticAttribute()`

🧪 Boolean and Null Constraints

Constraint Class	Purpose	Equivalent Assertion
`IsTrue()`	Asserts true	`assertTrue()`
`IsFalse()`	Asserts false	`assertFalse()`
`IsNull()`	Asserts null	`assertNull()`
`IsNotNull()`	Asserts not null	`assertNotNull()`
`IsEmpty()`	Asserts empty (string, array, etc.)	`assertEmpty()`
`IsNotEmpty()`	Asserts not empty	`assertNotEmpty()`

🧮 File System Constraints

Constraint Class	Purpose	Equivalent Assertion
`FileExists()`	Checks file exists	`assertFileExists()`
`FileDoesNotExist()`	Checks file does not exist	`assertFileDoesNotExist()`
`IsReadable()`	File is readable	`assertIsReadable()`
`IsWritable()`	File is writable	`assertIsWritable()`

🧩 Logical Constraints (combinators)

Constraint Class	Purpose	Notes
`LogicalAnd($c1, $c2)`	Passes if both constraints pass	Combines constraints
`LogicalOr($c1, $c2)`	Passes if either constraint passes
`LogicalNot($c)`	Inverts constraint result
`LogicalXor($c1, $c2)`	One passes, one fails