florianwolters/component-core-equality

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

v0.3.0 2014-05-31 12:54 UTC

README

Component\Core\Equality is a simple-to-use PHP component that implements equivalence relations on non-null object references.

Build Status Scrutinizer Code Quality Code Coverage SensioLabsInsight Coverage Status

Latest Stable Version Total Downloads Monthly Downloads Daily Downloads Latest Unstable Version License

Stories in Ready Dependency Status Dependencies Status HHVM Status

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:

  1. The interface 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: Implements a reference equivalence relation on non-null object references.
  3. The trait FlorianWolters\Component\Core\ValueEqualityTrait: Implements a value equivalence relation on non-null object references.
  4. The static class FlorianWolters\Component\Core\EqualityUtils: Offers operations for equivalence relations on non-null object references.

Features

  • Offers two default equivalence relation implementations:
  • Allows to create a custom equivalence relation by implementing the interface EqualityInterface, more precisely implementing the public method equals 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 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:
  • 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

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 trait ReferenceEqualityTrait or ValueEqualityTrait, 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.