florianwolters / component-core-equality
Implements equivalence relations on non-null object references as a PHP component.
Requires
- php: >=5.4
Requires (Dev)
- phpmd/phpmd: 2.*
- phpunit/phpunit: 4.*
- sami/sami: 1.*
- satooshi/php-coveralls: 0.*
- sebastian/phpcpd: 2.*
- sebastian/phpdcd: 1.*
- sensiolabs/security-checker: 1.*
- squizlabs/php_codesniffer: 2.*@dev
This package is not auto-updated.
Last update: 2024-10-26 14:13:38 UTC
README
Component\Core\Equality is a simple-to-use PHP component that
implements equivalence relations on non-null
object references.
Table of Contents (ToC)
Introduction
This component is inspired by the method java.lang.Object.equals
of the Java programming language.
Component\Core\Equality consists of four artifacts:
- The interface
FlorianWolters\Component\Core\EqualityInterface
: Indicates that an implementing class implements an equivalence relation on non-null
object references. - The trait
FlorianWolters\Component\Core\ReferenceEqualityTrait
: Implements a reference equivalence relation on non-null
object references. - The trait
FlorianWolters\Component\Core\ValueEqualityTrait
: Implements a value equivalence relation on non-null
object references. - The static class
FlorianWolters\Component\Core\EqualityUtils
: Offers operations for equivalence relations on non-null
object references.
Features
- Offers two default equivalence relation implementations:
- Reference Equality implemented via the trait
ReferenceEqualityTrait
. Refer to the section Usage below for an example. - Value Equality implemented via the trait
ValueEqualityTrait
. Refer to the section Usage below for an example.
- Reference Equality implemented via the trait
- Allows to create a custom equivalence relation by implementing the interface
EqualityInterface
, more precisely implementing the public methodequals
of that interface. Refer to the section Usage 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 returntrue
. - It is symmetric: for any non-
null
reference values$x
and$y
,$x->equals($y)
should returntrue
if and only if$y->equals($x)
returnstrue
. - It is transitive: for any non-
null
reference values$x
,$y
, and$z
, if$x->equals($y)
returnstrue
and$y->equals($z)
returnstrue
, then$x->equals($z)
should returntrue
. - It is consistent: for any non-
null
reference values$x
and$y
, multiple invocations of$x->equals($y)
consistently returntrue
or consistently returnfalse
, provided no information used inequals
comparisons on the objects is modified. - For any non-
null
reference value$x
,$x->equals(null)
should returnfalse
.
- It is reflexive: for any non-
- Artifacts tested with both static and dynamic test procedures:
- Dynamic component tests (unit and integration tests) implemented with PHPUnit.
- Static code analysis performed using the following tools:
- PHP_CodeSniffer: Style Checker
- PHP Mess Detector (PHPMD): Code Analyzer
- PHP Depend: Code Metrics
- phpcpd: Copy/Paste Detector (CPD)
- phpdcd: Dead Code Detector (DCD)
- SensioLabs Security Checker: Security Checker
- Continuous Integration (CI) using the following web services:
- Provides a Packagist package which can be installed using the dependency manager Composer. Click here for the package on Packagist.
- Provides a complete Application Programming Interface (API) documentation generated with the documentation generator Sami. Click here for the API documentation.
- Follows the following "standards" from the PHP Framework Interoperability
Group (FIG). PSR stands for PHP Standards Recommendation:
-
PSR-0: Autoloading Standards
Aims to provide a standard file, class and namespace convention to allow plug-and-play code.
-
PSR-1: Basic Coding Standard
Aims to ensure a high level of technical interoperability between shared PHP code.
-
PSR-2: Coding Style Guide
Provides a Coding Style Guide for projects looking to standardize their code.
-
PSR-4: Autoloader
A more modern take on autoloading reflecting advances in the ecosystem.
-
- Follows the Semantic Versioning (SemVer) specification version 2.0.0.
Requirements
Production
Development
- PHPUnit
- phpcpd
- phpdcd
- PHP_CodeSniffer
- PHP Mess Detector (PHPMD)
- Sami
- SensioLabs Security Checker
- php-coveralls
Installation
Component\Core\Equality should be installed using the dependency manager Composer.
Composer is a tool for dependency management in PHP. It allows you to declare the dependent libraries your project needs and it will install them in your project for you.
The Composer installer can be downloaded with php
.
php -r "readfile('https://getcomposer.org/installer');" | php
This will just check a few PHP settings and then download
composer.phar
to your working directory. This file is the Composer binary. It is a PHAR (PHP archive), which is an archive format for PHP 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
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
if using the traitReferenceEqualityTrait
orValueEqualityTrait
, since that allows Type Hinting.
The class EqualityExample
can be run via the command
php resources/php/EqualityExample.php
from the root of the project.
Reference Equality
The class ReferenceEqualityImpl
uses the Reference Equality
implementation of the trait ReferenceEqualityTrait
, that utilizes the
identity operator (===
) of PHP.
Value Equality
The class ValueEqualityImpl
uses the Value Equality implementation
of the trait ValueEqualityTrait
, that utilizes the equality operator
(==
) of PHP.
Custom Equality
One can define a custom equivalence relation by implementing the interface
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 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
.
Testing
phpunit
Contributing
Please see CONTRIBUTING for details.
Credits
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 https://gnu.org/licenses/lgpl.txt.