eloquent / equality
A better strict comparison for PHP.
Installs: 8 369
Dependents: 0
Suggesters: 0
Security: 0
Stars: 13
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: >=5.3
Requires (Dev)
- icecave/archer: ~1
README
A better strict comparison for PHP.
Deprecated
Equality is deprecated. Please use Parity instead.
Installation and documentation
- Available as Composer package eloquent/equality.
- API documentation available.
The problem
Sometimes it is necessary to compare two objects to determine whether they are considered equal.
If the ==
operator is used, there is no strictness about the equality. For
instance, this snippet outputs 'equal':
$left = new stdClass; $left->foo = 0; $right = new stdClass; $right->foo = null; if ($left == $right) { echo 'equal'; } else { echo 'not equal'; }
Conversely, if the ===
operator is used, objects are not equal unless they are
the same instance. The following snippet outputs 'not equal':
$left = new stdClass; $left->foo = 'bar'; $right = new stdClass; $right->foo = 'bar'; if ($left === $right) { echo 'equal'; } else { echo 'not equal'; }
Unfortunately PHP does not have an inbuilt method to compare objects strictly without requiring that they be the same instance. This is where Equality comes in. This snippet correctly outputs 'equal':
use Eloquent\Equality\Comparator; $left = new stdClass; $left->foo = 'bar'; $right = new stdClass; $right->foo = 'bar'; $comparator = new Comparator; if ($comparator->equals($left, $right)) { echo 'equal'; } else { echo 'not equal'; }
Usage
Equality is very simple to use. Simply instantiate a Comparator
and use its
equals()
method:
use Eloquent\Equality\Comparator; $comparator = new Comparator; if ($comparator->equals($left, $right)) { // equal } else { // not equal }
Equality can work with any PHP data type, not just objects.
Custom equality logic
In some cases it may be desirable to customize how equality is determined.
The interface EqualityComparable
can be used to provide a custom equality
implementation for any class:
use Eloquent\Equality\Comparator; use Eloquent\Equality\EqualityComparable; class Foo implements EqualityComparable { /** * @param mixed $value * @param Comparator $comparator * * @return boolean */ public function isEqualTo($value, Comparator $comparator) { // custom logic... } }
When Equality encounters an object that implements EqualityComparable
, it
will return the result of the isEqualTo()
method instead of using the default
equality logic. The comparator itself will be passed as the second parameter.
How does Equality work?
Equality uses reflection to recurse over the values it is passed and ensure that they are deeply, and strictly, equal.
In addition, it implements special protections to avoid infinite recursion issues, such as objects that contain themselves, or objects that contain the object that they are being compared to.