sebastian/comparator

Add this library as a dependency to your project using Composer. Use the standard command for production dependencies, or the --dev flag if you only require the library for development tasks like running a test suite.

composer require sebastian/comparator

If you only need this library during development (e.g., for testing), install it using the --dev flag.

composer require --dev sebastian/comparator

To compare two PHP values, use SebastianBergmann\Comparator\Factory to obtain the appropriate comparator for the given types. Use the returned comparator's assertEquals() method to perform the comparison. If the values are not equal, the method throws a SebastianBergmann\Comparator\ComparisonFailure exception.

<?php
use SebastianBergmann\Comparator\Factory;
use SebastianBergmann\Comparator\ComparisonFailure;

$date1 = new DateTime('2013-03-29 04:13:35', new DateTimeZone('America/New_York'));
$date2 = new DateTime('2013-03-29 03:13:35', new DateTimeZone('America/Chicago'));

$factory = new Factory;
$comparator = $factory->getComparatorFor($date1, $date2);

try {
    $comparator->assertEquals($date1, $date2);
    print "Dates match";
} catch (ComparisonFailure $failure) {
    print "Dates don't match";
}

The assertEquals method performs the comparison.

Parameters:

• mixed $expected: The expected object.
• mixed $actual: The actual object being tested.
• float $delta = 0.0: The delta used for float comparisons (inherited from ArrayComparator).
• bool $canonicalize = false: Whether to canonicalize values before comparison (inherited from ArrayComparator).
• bool $ignoreCase = false: Whether to ignore case in string comparisons (inherited from ArrayComparator).
• array &$processed = []: A reference to an array of previously processed pairs, used to prevent infinite recursion in cyclic dependencies.

Throws:

• ComparisonFailure: Thrown if the objects are of different classes or if their internal states do not match.

Use ScalarComparator::assertEquals() to assert that two scalar values (strings, integers, floats, booleans) or null values are equal. The method also supports comparing strings against objects that implement the __toString() method.

If the comparison fails, it throws a ComparisonFailure exception. For long strings, the failure message will automatically truncate common prefixes and suffixes to provide a concise diff.

Parameters

• mixed $expected: The expected value.
• mixed $actual: The actual value.
• float $delta = 0.0: Used for floating-point comparisons (though implementation details for delta usage in this specific class are internal).
• bool $canonicalize = false: Whether to canonicalize values before comparison.
• bool $ignoreCase = false: If true, performs a case-insensitive comparison using mb_strtolower with UTF-8 encoding.

Use ArrayComparator::assertEquals() to verify that two arrays are equal. By default, arrays are considered equal if they contain the same key-value pairs, regardless of key order.

If the $canonicalize parameter is set to true, the comparator will attempt to sort the arrays before comparison:

• For list-like arrays (sequential integer keys), it sorts the elements using an internal comparison logic.
• For associative arrays, it sorts the elements by their keys.

If the arrays are not equal, a ComparisonFailure is thrown.

The ObjectComparator::assertEquals() method compares two objects for equality. It first verifies that both objects are of the same class. If they are, it compares their internal state by converting them to arrays via the exporter.

Note that this class is marked as @internal and is not covered by the backward compatibility promise for sebastian/comparator.

The accepts(mixed $expected, mixed $actual): bool method determines if the ScalarComparator is capable of comparing the two provided values.

It returns true if:

1. Both values are scalars (or null).
2. One value is a string and the other is an object implementing __toString().
3. One value is an object implementing __toString() and the other is a string.

The assertEquals method accepts the following parameters:

• mixed $expected: The expected array value.
• mixed $actual: The actual array value.
• float $delta: The delta used for floating-point comparisons (defaults to 0.0).
• bool $canonicalize: If true, sorts arrays (lists by value, associative arrays by key) before comparing. Defaults to false.
• bool $ignoreCase: If true, ignores case in string comparisons (defaults to false).
• array &$processed: A reference to an array used to track already processed elements to prevent infinite recursion. Defaults to [].