README

这个 PHP 库为 PHP 7.1+ 提供了枚举功能，包括一个 Enum 接口，一个 AbstractEnum 基础类，以及一个 AbstractAutoEnum 基础类。

它是在 MIT 许可证 下发布的。

安装和依赖

通过 Composer: $ composer require mle86/enum

或者将其插入到你的项目的 composer.json 文件中

"require": {
    "mle86/enum": "^0"
}

它的唯一依赖是 mle86/value 库。

最低 PHP 版本

PHP 7.1

使用方法

要 实现一个自定义的 Enum 类，只需扩展 AbstractAutoEnum 基础类并添加一些公共常量

<?php
class TriState extends \mle86\Enum\AbstractAutoEnum
{
    public const HIGH  = 'H';
    public const LOW   = 'L';
    public const UNDEF = 'Z';
}

为了更好地控制哪些值被你的类视为有效，可以重写 isValid() 类方法或扩展更通用的 AbstractEnum 基础类。
不过请注意，枚举类基本上是基于一个在编译时已知的 硬编码的接受值列表；如果你想根据模式或复杂的验证逻辑接受值，考虑使用值对象类，如 Value。

使用枚举类有以下三种方法：

1. 仅使用类常量。
   实际上不需要这个库来做这个，因为你可以简单地编写一个独立的类来完成这个任务，但这确实是一个可能性。

2. 构建实例并在你的方法中使用类型提示。
   AbstractEnum 和 AbstractAutoEnum 基础类有一个默认构造函数，并在实例中包装单个有效的枚举值。包装的值可以通过 value() 获取器检索，但也可以通过默认的 __toString() 和 jsonSerialize() 方法返回。

3. 使用 validate() 和 validateOptional() 方法在方法中强制正确的类型。
   如果你不想构建枚举类的实例以避免对象开销，或者简单地因为接收到的输入值不是对象（例如来自 JSON API），你也可以使用两个 validate 方法来检查原始输入值。它们将接受原始值和实例，返回 void，并在输入无效时抛出 EnumValueException。`validateOptional()` 方法也接受 NULL 值。

带有实例和枚举类型提示的示例

<?php
$state = new TriState(TriState::HIGH);

var_dump($state->value());     // H
var_dump(json_encode($state)); // "H"
var_dump($state->equals(TriState::HIGH)); // true
var_dump($state->equals(TriState::LOW));  // false

function (TriState $state) {
    // $state is definitely a TriState instance here,
    // so it definitely wraps a valid TriState constant.
}

没有类型提示和更明确的验证的另一个示例

<?php
function ($state, $optionalState = null) {
    TriState::validate($state);
    // Now we can be sure that $state contains a valid TriState value
    // (or maybe it's even a TriState instance).
    
    TriState::validateOptional($optionalState);
    // Now we know that $optionalState contains either
    // a valid TriState value,
    // a valid TriState instance,
    // or NULL.
}

类和接口

• Enum 基础接口
  • AbstractEnum 基类。
    • AbstractAutoEnum 基类。
• AutoEnumTrait 特性。
• 异常 类。

更多文档

• 枚举继承 – 如何扩展枚举类。
• 序列化 – 枚举实例如何序列化。
• 类型安全 – 关于枚举值类型和类型转换的说明。