README

Component\Core\Equality 是一个简单易用的 PHP 组件，它实现了非-null 对象引用上的等价关系。

目录

• 介绍
• 特性
• 要求
• 用法
• 安装
• 测试
• 贡献
• 致谢
• 许可

介绍

此组件灵感来源于java.lang.Object.equals 方法，该方法用于Java 编程语言。

Component\Core\Equality 由四个工件组成

1. 接口 FlorianWolters\Component\Core\EqualityInterface：表示实现类实现了非-null 对象引用上的等价关系。
2. 特质 FlorianWolters\Component\Core\ReferenceEqualityTrait：实现了非-null 对象引用上的引用等价关系。
3. 特质 FlorianWolters\Component\Core\ValueEqualityTrait：实现了非-null 对象引用上的值等价关系。
4. 静态类 FlorianWolters\Component\Core\EqualityUtils：提供非-null 对象引用上等价关系的操作。

特性

• 提供两种默认等价关系实现
  • 引用等价 通过特质 ReferenceEqualityTrait 实现。下面将提供使用示例。
  • 值等价 通过特质 ValueEqualityTrait 实现。下面将提供使用示例。
• 允许通过实现接口 EqualityInterface 来创建自定义等价关系，更具体地说，是实现该接口的公共方法 equals。下面将提供使用示例。
• equals 方法实现了非-null 对象引用上的等价关系
  • 它是自反的：对于任何非-null 引用值 $x，$x->equals($x) 应该返回 true。
  • 它是对称的：对于任何非-null 引用值 $x 和 $y，如果且仅当 $y->equals($x) 返回 true 时，$x->equals($y) 才会返回 true。
  • 它是传递性的：对于任何非null引用值 $x、$y 和 $z，如果 $x->equals($y) 返回 true 且 $y->equals($z) 返回 true，则 $x->equals($z) 应返回 true。
  • 它是一致的：对于任何非null引用值 $x 和 $y，多次调用 $x->equals($y) 一致地返回 true 或一致地返回 false，前提是在对象上用于 equals 比较的信息没有被修改。
  • 对于任何非null引用值 $x，$x->equals(null) 应返回 false。
• 使用静态和动态测试程序测试的工件
  • 使用PHPUnit实现了动态组件测试（单元和集成测试）。
  • 使用以下工具执行静态代码分析
    • PHP_CodeSniffer：样式检查器
    • PHP Mess Detector (PHPMD)：代码分析器
    • PHP Depend：代码度量
    • phpcpd：复制/粘贴检测器（CPD）
    • phpdcd：死代码检测器（DCD）
    • SensioLabs Security Checker：安全检查器
  • 使用以下网络服务进行持续集成（CI）
    • Scrutinizer CI
    • SensioLabsInsight
    • Coveralls
    • VersionEye
    • Depending
    • Waffle
• 提供一个Packagist软件包，可以使用依赖管理器Composer进行安装。点击这里查看 Packagist 上的软件包。
• 提供一个完整的应用程序编程接口（API）文档，该文档使用文档生成器Sami生成。点击这里查看 API 文档。
• 遵循PHP 框架互操作性小组（FIG）的以下“标准”。PSR代表PHP标准建议

  • PSR-0：自动加载标准

    旨在提供一个标准的文件、类和命名空间约定，以允许即插即用的代码。

  • PSR-1：基本编码标准

    旨在确保共享PHP代码之间的高度技术互操作性。

  • PSR-2：编码风格指南

    为希望标准化其代码的项目提供编码风格指南。

  • PSR-4：自动加载器

    是自动加载的更现代的方法，反映了生态系统的进步。

• 遵循语义版本控制（SemVer）规范2.0.0版本。

要求

生产

• PHP >= 5.4
• Composer

开发

• PHPUnit
• phpcpd
• phpdcd
• PHP_CodeSniffer
• PHP Mess Detector (PHPMD)
• Sami
• SensioLabs Security Checker
• php-coveralls

安装

Component\Core\Equality应使用依赖管理器Composer安装。

Composer 是一个用于 PHP 依赖管理的工具。它允许您声明项目所需的依赖库，并为您在项目中安装它们。

Composer 安装程序可以使用 php 下载。

php -r "readfile('https://composer.php.ac.cn/installer');" | php

这将仅检查一些 PHP 设置，然后下载 composer.phar 到您的当前工作目录。该文件是 Composer 二进制文件。它是一个 PHAR（《PHP 归档》），是一种 PHP 归档格式，可以在命令行上运行，等等。

要解析和下载依赖项，请运行 install 命令

php composer.phar install

如果您正在创建一个依赖于 Component\Core\Equality 的组件，请确保将 Component\Core\Equality 添加到组件的 composer.json 文件中

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

用法

Component\Core\Equality 的最佳文档是包含在包中的单元测试

最重要的使用规则

如果您使用 ReferenceEqualityTrait 或 ValueEqualityTrait 特性，请始终实现接口 EqualityInterface，因为这样可以允许 类型提示。

类 EqualityExample 可以通过在项目根目录下运行 php resources/php/EqualityExample.php 命令来运行。

引用相等性

类 ReferenceEqualityImpl 使用了特质的 引用相等性 实现 ReferenceEqualityTrait，该实现利用了 PHP 的身份运算符（===）。

值相等性

类 ValueEqualityImpl 使用了特质的 值相等性 实现 ValueEqualityTrait，该实现利用了 PHP 的相等运算符（==）。

自定义相等性

可以通过实现接口 EqualityInterface 定义一个自定义的等价关系，更具体地说，是实现该接口的公共方法 equals。

注意：等价关系必须是 自反的、对称的、传递的 和 一致的。有关这些特性的更详细解释，请参阅功能部分。

使用类 CustomEqualityImpl 展示了为简单的 域对象 定义的等价关系的示例。

测试

phpunit

贡献

请参阅CONTRIBUTING以获取详细信息。

致谢

• Florian Wolters
• 所有贡献者

许可

本程序是自由软件：您可以在自由软件基金会发布的GNU Lesser General Public License的条款下重新分发和/或修改本程序，许可证版本为3或（根据您的选择）任何更高版本。

本程序的发布是出于希望它将是有用的，但没有任何保证；甚至没有关于其商誉或适用于特定目的的暗示性保证。有关更多信息，请参阅GNU Lesser General Public License。

您应该已收到随本程序一起提供的GNU Lesser General Public License副本。如果没有，请参阅https://gnu.org/licenses/lgpl.txt。