PHPackages                             florianwolters/component-core-equality - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. florianwolters/component-core-equality

ActiveLibrary[Utility & Helpers](/categories/utility)

florianwolters/component-core-equality
======================================

Implements equivalence relations on non-null object references as a PHP component.

v0.3.0(11y ago)16982LGPL-3.0+PHPPHP >=5.4

Since Sep 24Pushed 11y ago2 watchersCompare

[ Source](https://github.com/FlorianWolters/PHP-Component-Core-Equality)[ Packagist](https://packagist.org/packages/florianwolters/component-core-equality)[ Docs](http://github.com/FlorianWolters/PHP-Component-Core-Equality)[ RSS](/packages/florianwolters-component-core-equality/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (8)Versions (5)Used By (2)

Component\\Core\\Equality
=========================

[](#componentcoreequality)

**Component\\Core\\Equality** is a simple-to-use [PHP](https://php.net "PHP: Hypertext Preprocessor") component that implements equivalence relations on non-`null` object references.

[![Build Status](https://camo.githubusercontent.com/c9014edb88cb6a37460eb00d5a18f7ef996318025c0b5998a5908ed6a75cc4d8/68747470733a2f2f7472617669732d63692e6f72672f466c6f7269616e576f6c746572732f5048502d436f6d706f6e656e742d436f72652d457175616c6974792e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/FlorianWolters/PHP-Component-Core-Equality)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/0601ce02a33a92af337529592b1ffdb5891ce37cb307b88acf07645bbd496a90/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f466c6f7269616e576f6c746572732f5048502d436f6d706f6e656e742d436f72652d457175616c6974792f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/FlorianWolters/PHP-Component-Core-Equality/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/2edeeaf3e84ef69365be147d0b08fdc5d4fab0bc2e79109fd25b9219fe95d306/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f466c6f7269616e576f6c746572732f5048502d436f6d706f6e656e742d436f72652d457175616c6974792f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/FlorianWolters/PHP-Component-Core-Equality/?branch=master)[![SensioLabsInsight](https://camo.githubusercontent.com/cd0e49030fdf70b4754fb2c5a472933aa166bad1d35e508d1e234638a4a885eb/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f32663066393534332d343739392d346564312d396335372d3939393632636634373737312f6d696e692e706e67)](https://insight.sensiolabs.com/projects/2f0f9543-4799-4ed1-9c57-99962cf47771)[![Coverage Status](https://camo.githubusercontent.com/211a18e7bfd7c27e618acdcc9d7dd2134ddbc2806b0bafd90af953c115642717/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f466c6f7269616e576f6c746572732f5048502d436f6d706f6e656e742d436f72652d457175616c6974792e737667)](https://coveralls.io/r/FlorianWolters/PHP-Component-Core-Equality?branch=master)

[![Latest Stable Version](https://camo.githubusercontent.com/45c48533f29d47ed9d1a2a154f91a7e3672a5a9da415ef6417840382d5d19b5b/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f762f737461626c652e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)[![Total Downloads](https://camo.githubusercontent.com/e9c4458dbe329d18eb46e8adf6db44ccf4b7223b5dabace69572a4daf3a561fb/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f646f776e6c6f6164732e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)[![Monthly Downloads](https://camo.githubusercontent.com/3377e297fe910bb6c4d9c28f68e59804ff58837de32d81f7a4c1db30a3d0b80a/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f642f6d6f6e74686c792e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)[![Daily Downloads](https://camo.githubusercontent.com/cdad29b4c5039c4cd6062ce2e4a2079d73e016a6395ed889b510c261844c53f6/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f642f6461696c792e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)[![Latest Unstable Version](https://camo.githubusercontent.com/b4c2ced654da26b28c39ae9a8015c74a57b83f4b5f6455f9eeee9fd439517aff/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f762f756e737461626c652e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)[![License](https://camo.githubusercontent.com/c22af22fc4982530e9b4dfd6761c39d1e3abc6b29842468cc36efd26bcc28868/68747470733a2f2f706f7365722e707567782e6f72672f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792f6c6963656e73652e706e67)](https://packagist.org/packages/florianwolters/component-core-equality)

[![Stories in Ready](https://camo.githubusercontent.com/6b399a52aa1933cf60097d1ddc836d4255523d7e4796b4fa102c157175d38546/68747470733a2f2f62616467652e776166666c652e696f2f666c6f7269616e776f6c746572732f7068702d636f6d706f6e656e742d636f72652d657175616c6974792e706e673f6c6162656c3d7265616479267469746c653d5265616479)](https://waffle.io/florianwolters/php-component-core-equality)[![Dependency Status](https://camo.githubusercontent.com/83597ace4e003149713e08f895dad45e4cae3fd5a4ded90e19dc68fe28b78b86/68747470733a2f2f7777772e76657273696f6e6579652e636f6d2f757365722f70726f6a656374732f3531633333306664353836326334303030323030303534312f62616467652e737667)](https://www.versioneye.com/user/projects/51c330fd5862c40002000541)[![Dependencies Status](https://camo.githubusercontent.com/09afd1c86d63b170c0b433d0b7570da187dd7f340bd9ba41542172f0f20cee29/68747470733a2f2f646570656e64696e672e696e2f466c6f7269616e576f6c746572732f5048502d436f6d706f6e656e742d436f72652d457175616c6974792e706e67)](http://depending.in/FlorianWolters/PHP-Component-Core-Equality)[![HHVM Status](https://camo.githubusercontent.com/7fc1f84d9c38f1557e90f89e407ae5961161707445231a35542fc47da323ccf0/687474703a2f2f6868766d2e683463632e64652f62616467652f666c6f7269616e776f6c746572732f636f6d706f6e656e742d636f72652d657175616c6974792e706e67)](http://hhvm.h4cc.de/package/florianwolters/component-core-equality)

Table of Contents (ToC)
-----------------------

[](#table-of-contents-toc)

- [Introduction](#introduction)
- [Features](#features)
- [Requirements](#requirements)
- [Usage](#usage)
- [Installation](#installation)
- [Testing](#testing)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Introduction
------------

[](#introduction)

This component is inspired by the method [`java.lang.Object.equals`](http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html#equals(java.lang.Object) "Object (Java Platform SE 7)") of the [Java](http://java.com "Java") programming language.

**Component\\Core\\Equality** consists of four artifacts:

1. The interface [`FlorianWolters\Component\Core\EqualityInterface`](src/main/php/EqualityInterface.php "FlorianWolters\Component\Core\EqualityInterface"): Indicates that an implementing class implements an equivalence relation on non-`null` object references.
2. The trait [`FlorianWolters\Component\Core\ReferenceEqualityTrait`](src/main/php/ReferenceEqualityTrait.php "FlorianWolters\Component\Core\ReferenceEqualityTrait"): Implements a **reference** equivalence relation on non-`null` object references.
3. The trait [`FlorianWolters\Component\Core\ValueEqualityTrait`](src/main/php/ValueEqualityTrait.php "FlorianWolters\Component\Core\ValueEqualityTrait"): Implements a **value** equivalence relation on non-`null` object references.
4. The static class [`FlorianWolters\Component\Core\EqualityUtils`](src/main/php/EqualityUtils.php "FlorianWolters\Component\Core\EqualityUtils"): Offers operations for equivalence relations on non-`null` object references.

Features
--------

[](#features)

- Offers two default equivalence relation implementations:
    - **Reference Equality** implemented via the trait [`ReferenceEqualityTrait`](src/main/php/ReferenceEqualityTrait.php "FlorianWolters\Component\Core\ReferenceEqualityTrait"). Refer to the section [Usage](#reference-equality) below for an example.
    - **Value Equality** implemented via the trait [`ValueEqualityTrait`](src/main/php/ValueEqualityTrait.php "FlorianWolters\Component\Core\ValueEqualityTrait"). Refer to the section [Usage](#value-equality) below for an example.
- Allows to create a custom equivalence relation by implementing the interface [`EqualityInterface`](src/main/php/EqualityInterface.php "FlorianWolters\Component\Core\EqualityInterface"), more precisely implementing the public method `equals` of that interface. Refer to the section [Usage](#custom-equality)below for an example.
- The `equals` method implements an equivalence relation on non-`null` object references:
    - It is *reflexive*: for any non-`null` reference value `$x`, `$x->equals($x)`should return `true`.
    - It is *symmetric*: for any non-`null` reference values `$x` and `$y`, `$x->equals($y)` should return `true` if and only if `$y->equals($x)`returns `true`.
    - It is *transitive*: for any non-`null` reference values `$x`, `$y`, and `$z`, if `$x->equals($y)` returns `true` and `$y->equals($z)` returns `true`, then `$x->equals($z)` should return `true`.
    - It is *consistent*: for any non-`null` reference values `$x` and `$y`, multiple invocations of `$x->equals($y)` consistently return `true` or consistently return `false`, provided no information used in `equals`comparisons on the objects is modified.
    - For any non-`null` reference value `$x`, `$x->equals(null)` should return `false`.
- Artifacts tested with both static and dynamic test procedures:
    - Dynamic component tests (unit and integration tests) implemented with [PHPUnit](https://phpunit.de "PHPUnit").
    - Static code analysis performed using the following tools:
        - [PHP\_CodeSniffer](https://pear.php.net/package/PHP_CodeSniffer "PHP_CodeSniffer"): Style Checker
        - [PHP Mess Detector (PHPMD)](http://phpmd.org "PHPMD - PHP Mess Detector"): Code Analyzer
        - [PHP Depend](http://pdepend.org "PHP Depend - Software Metrics for PHP"): Code Metrics
        - [phpcpd](https://github.com/sebastianbergmann/phpcpd "sebastianbergmann/phpcpd · GitHub"): Copy/Paste Detector (CPD)
        - [phpdcd](https://github.com/sebastianbergmann/phpdcd "sebastianbergmann/phpdcd · GitHub"): Dead Code Detector (DCD)
        - [SensioLabs Security Checker](https://github.com/sensiolabs/security-checker "SensioLabs Security Checker"): Security Checker
    - Continuous Integration (CI) using the following web services:
        - [Scrutinizer CI](https://scrutinizer-ci.com "Scrutinizer CI")
        - [SensioLabsInsight](https://insight.sensiolabs.com "SensioLabsInsight")
        - [Coveralls](https://coveralls.io "Coveralls")
        - [VersionEye](https://versioneye.com "VersionEye")
        - [Depending](https://depending.in "Depending")
        - [Waffle](https://waffle.io "Waffle")
- Provides a [Packagist](https://packagist.org "Packagist") package which can be installed using the dependency manager [Composer](https://getcomposer.org "Composer"). Click [here](https://packagist.org/packages/florianwolters/component-core-equality "florianwolters/component-core-equality - Packagist") for the package on [Packagist](https://packagist.org "Packagist").
- Provides a complete Application Programming Interface (API) documentation generated with the documentation generator [Sami](https://github.com/fabpot/sami "fabpot/sami · GitHub"). Click [here](http://blog.florianwolters.de/PHP-Component-Core-Equality "Application Programming Interface (API) documentation") for the API documentation.
- Follows the following "standards" from the [PHP Framework Interoperability Group (FIG)](http://php-fig.org "PHP-FIG — PHP Framework Interop Group"). PSR stands for PHP Standards Recommendation:
    - [PSR-0](http://php-fig.org/psr/psr-0 "PSR-0 requirements for autoloader interoperability"): Autoloading Standards

        > Aims to provide a standard file, class and namespace convention to allow plug-and-play code.
    - [PSR-1](http://php-fig.org/psr/psr-1 "PSR-1 basic coding style guide"): Basic Coding Standard

        > Aims to ensure a high level of technical interoperability between shared PHP code.
    - [PSR-2](http://php-fig.org/psr/psr-2 "PSR-2 coding style guide"): Coding Style Guide

        > Provides a Coding Style Guide for projects looking to standardize their code.
    - [PSR-4](http://php-fig.org/psr/psr-4 "PSR-4: Improved Autoloading"): Autoloader

        > A more modern take on autoloading reflecting advances in the ecosystem.
- Follows the [Semantic Versioning](http://semver.org "Semantic Versioning") (SemVer) specification version 2.0.0.

Requirements
------------

[](#requirements)

### Production

[](#production)

- [PHP](https://php.net "PHP: Hypertext Preprocessor") >= 5.4
- [Composer](https://getcomposer.org "Composer")

### Development

[](#development)

- [PHPUnit](https://phpunit.de "PHPUnit")
- [phpcpd](https://github.com/sebastianbergmann/phpcpd "sebastianbergmann/phpcpd · GitHub")
- [phpdcd](https://github.com/sebastianbergmann/phpdcd "sebastianbergmann/phpdcd · GitHub")
- [PHP\_CodeSniffer](https://pear.php.net/package/PHP_CodeSniffer "PHP_CodeSniffer")
- [PHP Mess Detector (PHPMD)](http://phpmd.org "PHPMD - PHP Mess Detector")
- [Sami](https://github.com/fabpot/sami "fabpot/sami · GitHub")
- [SensioLabs Security Checker](https://github.com/sensiolabs/security-checker "SensioLabs Security Checker")
- [php-coveralls](https://github.com/satooshi/php-coveralls "satooshi/php-coveralls · GitHub")

Installation
------------

[](#installation)

**Component\\Core\\Equality** should be installed using the dependency manager [Composer](https://getcomposer.org "Composer").

> [Composer](https://getcomposer.org "Composer") is a tool for dependency management in [PHP](https://php.net "PHP: Hypertext Preprocessor"). It allows you to declare the dependent libraries your project needs and it will install them in your project for you.

The [Composer](https://getcomposer.org "Composer") installer can be downloaded with `php`.

```
php -r "readfile('https://getcomposer.org/installer');" | php

```

> This will just check a few [PHP](https://php.net "PHP: Hypertext Preprocessor") settings and then download `composer.phar`to your working directory. This file is the [Composer](https://getcomposer.org "Composer") binary. It is a PHAR ([PHP](https://php.net "PHP: Hypertext Preprocessor") archive), which is an archive format for [PHP](https://php.net "PHP: Hypertext Preprocessor") which can be run on the command line, amongst other things.

> To resolve and download dependencies, run the `install` command:

```
php composer.phar install

```

If you are creating a component that relies on **Component\\Core\\Equality**, please make sure that you add **Component\\Core\\Equality** to your component's `composer.json` file:

```
{
    "require": {
        "florianwolters/component-core-equality": "0.3.*"
    }
}
```

Usage
-----

[](#usage)

The best documentation for **Component\\Core\\Equality** are the unit tests, which are shipped in the package.

The most important usage rule:

> Always implement the interface [`EqualityInterface`](src/main/php/EqualityInterface.php "FlorianWolters\Component\Core\EqualityInterface") if using the trait [`ReferenceEqualityTrait`](src/main/php/ReferenceEqualityTrait.php "FlorianWolters\Component\Core\ReferenceEqualityTrait") or [`ValueEqualityTrait`](src/main/php/ValueEqualityTrait.php "FlorianWolters\Component\Core\ValueEqualityTrait"), since that allows [Type Hinting](https://php.net/language.oop5.typehinting "PHP: Type Hinting - Manual").

The class [`EqualityExample`](resources/php/EqualityExample.php "FlorianWolters\Example\EqualityExample") can be run via the command `php resources/php/EqualityExample.php` from the root of the project.

### Reference Equality

[](#reference-equality)

The class [`ReferenceEqualityImpl`](src/test/resources/ReferenceEqualityImpl.php "FlorianWolters\Example\ReferenceEqualityImpl") uses the **Reference Equality**implementation of the trait [`ReferenceEqualityTrait`](src/main/php/ReferenceEqualityTrait.php "FlorianWolters\Component\Core\ReferenceEqualityTrait"), that utilizes the identity operator (`===`) of [PHP](https://php.net "PHP: Hypertext Preprocessor").

### Value Equality

[](#value-equality)

The class [`ValueEqualityImpl`](src/test/resources/ValueEqualityImpl.php "FlorianWolters\Example\ValueEqualityImpl") uses the **Value Equality** implementation of the trait [`ValueEqualityTrait`](src/main/php/ValueEqualityTrait.php "FlorianWolters\Component\Core\ValueEqualityTrait"), that utilizes the equality operator (`==`) of [PHP](https://php.net "PHP: Hypertext Preprocessor").

### Custom Equality

[](#custom-equality)

One can define a custom equivalence relation by implementing the interface [`EqualityInterface`](src/main/php/EqualityInterface.php "FlorianWolters\Component\Core\EqualityInterface"), more precisely implementing the public method `equals` of that interface.

---

**Note:** The equivalence relations must be *reflexive*, *symmetric*, *transitive* and *consistent*. Refer to the section [Features](#features) for a more detailed explanation of these characteristics.

---

An example for a custom equivalence relation for a simple *Domain Object* is shown with the class [`CustomEqualityImpl`](resources/php/CustomEqualityImpl.php "FlorianWolters\Example\CustomEqualityImpl").

Testing
-------

[](#testing)

```
phpunit

```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [Florian Wolters](https://github.com/FlorianWolters "FlorianWolters · GitHub")
- [All Contributors](https://github.com/FlorianWolters/PHP-Component-Core-Equality/contributors "Contributors to FlorianWolters/PHP-Component-Core-Equality")

License
-------

[](#license)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see .

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity17

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~204 days

Total

4

Last Release

4361d ago

PHP version history (2 changes)v0.1.0-betaPHP >=5.3.0

v0.1.1PHP >=5.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/75dd7e42d69a87c4a0c68b4f29f5d223eb1f9a3f647abafa72da80d2a06d2442?d=identicon)[FlorianWolters](/maintainers/FlorianWolters)

---

Top Contributors

[![FlorianWolters](https://avatars.githubusercontent.com/u/1318837?v=4)](https://github.com/FlorianWolters "FlorianWolters (54 commits)")

---

Tags

equalitycorecomparisonequalsreference equalityvalue equality

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/florianwolters-component-core-equality/health.svg)

```
[![Health](https://phpackages.com/badges/florianwolters-component-core-equality/health.svg)](https://phpackages.com/packages/florianwolters-component-core-equality)
```

###  Alternatives

[nette/utils

🛠 Nette Utils: lightweight utilities for string & array manipulation, image handling, safe JSON encoding/decoding, validation, slug or strong password generating etc.

2.1k394.3M1.5k](/packages/nette-utils)[fidry/cpu-core-counter

Tiny utility to get the number of CPU cores.

238148.2M23](/packages/fidry-cpu-core-counter)[icecave/parity

A customizable deep comparison library.

516.8M10](/packages/icecave-parity)[phootwork/lang

Missing PHP language constructs

1224.8M8](/packages/phootwork-lang)[atomescrochus/laravel-string-similarities

Compare two string and get a similarity percentage

70160.1k2](/packages/atomescrochus-laravel-string-similarities)[dragon-code/benchmark

Simple comparison of code execution speed between different options

11934.7k5](/packages/dragon-code-benchmark)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)