webmozarts/strict-phpunit

Enables type-safe comparisons of objects in PHPUnit

Maintainers

👁 webmozart

Package info

github.com/webmozarts/strict-phpunit

pkg:composer/webmozarts/strict-phpunit

Statistics

Installs: 307 898

Dependents: 4

Suggesters: 1

Stars: 30

Open Issues: 0

7.24.1 2026-03-20 11:41 UTC

Requires

Requires (Dev)

Suggests

None

Provides

None

Conflicts

None

Replaces

None

MIT 4227331891f45ce9d10b995393f6cb90b9e3df37

  • Bernhard Schussek <bernhard.schussek.woop@webmozarts.com>

This package is auto-updated.

Last update: 2026-06-03 07:08:15 UTC

README

Caution

This repository is read-only. To submit any changes, check out [php-libraries].

Enables type-safe comparisons of objects in PHPUnit.

Problem

PHPUnit has a very powerful comparison system that helps you to compare objects with expected values:

class ValueObject
{
 public ?string $property;
 
 public function __construct(?string $property)
 {
 $this->property = $property;
 }
}

$actual = new ValueObject('foo!');

self::assertEquals(new ValueObject('foo'), $actual);
// => fails with a very helpful error message

This comparison system will give you a meaningful exception that guides you precisely to the problem that caused the assertion to fail. Strings are furthermore diffed so that you see exactly which character of the string causes a mismatch.

PHPUnit compares each scalar property of an object with relaxed types. It is a little more intelligent than using just == under the hood, but still that will not always provide the results you want:

var_dump('Hi' == true);
// => true

self::assertEquals(new ValueObject('Hi'), new ValueObject(true));
// => fails

var_dump('' == null);
// => true

self::assertEquals(new ValueObject(''), new ValueObject(null));
// => succeeds

Solution

This extension enables a comparator for scalar values that fights this problem. With this extension, whenever PHPUnit finds a scalar value during assertEquals() (even recursively within objects or arrays), it will compare the value with ===.

Objects are still not checked for identity, hence you can still construct example objects to compare against.

Error messages stay meaningful.

self::assertEquals(new ValueObject(''), new ValueObject(null));
// => fails with a meaningful error

self::assertEquals(new ValueObject('foo!'), new ValueObject('foo'));
// => fails with a meaningful error

self::assertEquals(new ValueObject('foo!'), new ValueObject('foo!'));
// => succeeds

Installation

The extension can be installed with Composer:

composer require --dev webmozarts/strict-phpunit

Add the extension to your phpunit.xml.dist file to enable it:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd">
 <!-- ... -->
 
 <extensions>
 <bootstrap class="Webmozarts\StrictPHPUnit\StrictPHPUnitExtension"/>
 </extensions>
 
 <!-- ... -->
</phpunit>

Authors

Contribute

Contributions to the package are always welcome!

Note that this repository is a subtree-split of a monorepo and hence read only. PRs will be ported to the (internal) monorepo.

License

All contents of this package are licensed under the MIT license.