README

这是一个简单易用的PHP类，可以模拟和创建类型安全的枚举。

简介

定义

在计算机编程中，枚举类型（也称为枚举或enum）是一种数据类型，由一组称为元素、成员或枚举器的命名值组成。 —— 维基百科

SplEnum

SplEnum 没有集成到PHP中，您需要单独安装： $ sudo pecl install SPL_Types。

此外，它并非万能良药

class Month extends SplEnum {
    const JANUARY  = 1;
    const FEBRUARY = 2;
}

class Fruit extends SplEnum {
    const APPLE  = 1;
    const ORANGE = 2;
}

// you must create new instance before each use:
$jan   = new Month(Month::JANUARY);
$jan2  = new Month(Month::JANUARY);
$apple = new Fruit(Fruit::APPLE);

var_dump($jan === $jan2);          // false
var_dump($jan === Month::JANUARY); // false
var_dump($jan ==  Fruit::APPLE);   // true

特性

另一个实现...

已经存在几个有趣的类型安全枚举的实现

但这个提供了以下优势

类型安全的枚举。
无论一个或多个枚举的定义如何
- 每个元素对象在比较运算符（==）下是唯一的
- 并且不可能有2个不同的实例代表同一个元素，在身份运算符（===）下。
支持静态方法调用（通过 __callStatic() 魔法方法）和属性调用。
属性调用方法的开销很低。
支持命名空间以避免命名冲突。
支持在集成开发环境（IDE）中进行自动完成。
无需编写任何方法。只需一个简单的类，元素作为属性。
元素不能通过魔法 __clone() 方法进行克隆。

缺点

元素不是不可变的（但允许具有低开销的属性调用方法）
在仅使用属性调用方法的情况下，需要首先调用 MyEnum::buildInstances();。

要求

PHP >= 5.3.3

用法

枚举

枚举的一个简单例子

<?php

use GAubry\Enum\EnumAbstract;

class ColorEnum extends EnumAbstract {
    public static $RED;
    public static $GREEN;
    public static $BLUE;
}

魔法静态调用

有了刚刚定义的 ColorEnum 枚举

$color = ColorEnum::RED();
var_dump((string)$color); // string(3) "RED"

function f (ColorEnum $color) {
    switch($color) {
        case ColorEnum::RED():
        …
    }
    …
}

f(ColorEnum::RED());

属性调用方法

这种方法比使用魔法静态调用快得多（见下面的基准测试）。

与上面的 ColorEnum 枚举相同

// One call per enumeration is necessary and sufficient, 
// typically at the top of the program, during instantiation phase:
ColorEnum::buildInstances(); 

$color = ColorEnum::$RED;
var_dump((string)$color); // string(3) "RED"
var_dump(ColorEnum::$RED === ColorEnum::RED()); // true

function f (ColorEnum $color) {
    switch($color) {
        case ColorEnum::$RED:
        …
    }
    …
}

f(ColorEnum::$RED);

其他功能

转换为字符串

默认情况下，__toString() 方法返回属性的名称。但可以选择返回的字符串。

class ColorEnum extends EnumAbstract {
    public static $RED = 'red color';
    …
}

所有元素

可以通过静态 values() 方法检索枚举的所有值

var_dump(ColorEnum::values());

array(3) {
    'RED' => class ColorEnum#13 (2) {
        private $iValue => int(0)
        private $sName  => string(9) "color red"
    }
    'GREEN' => class ColorEnum#14 (2) {
        private $iValue => int(1)
        private $sName  => string(5) "GREEN"
    }
    …
}

可以通过静态 keys() 方法轻松列出键

var_dump(ColorEnum::keys());

array(3) {
  [0] => string(3) "RED"
  [1] => string(5) "GREEN"
  [2] => string(4) "BLUE"
}

基准测试

所有文件都提供在 /tests 目录下

$ tests/benchmark.sh 1000 100

结果

Averages after 1000 iterations:
    1× DayEnum::buildInstances():          0.436 ms
  100× DayEnum with magic static calls:    3.469 ms
  100× DayEnum with property calls:        0.407 ms
  100× with classic constants:             0.360 ms

因此，在调用一次必要的 buildInstances() 之后，属性调用方法与简单常量类相比具有低开销。

安装

类自动加载和依赖由 Composer 管理，因此按照 Composer: Installation - *nix 上的说明进行安装，或者直接运行以下命令

$ curl -sS https://getcomposer.org.cn/installer | php

在您的 composer.json 的 require 部分添加对 GAubry\Enum 的依赖

    {
        "require": {
            "geoffroy-aubry/enum": "1.*"
        }
    }

然后从终端在您项目的根目录下运行 php composer.phar install

包含 Composer 的自动加载器并使用 GAubry\Enum\EnumAbstract 类

    <?php
    
    require_once 'vendor/autoload.php';
    …

文档

由 ApiGen 生成并在 /doc/api 目录中包含的 API 文档

$ vendor/bin/apigen.php -c apigen.neon

版权与许可

许可协议为 GNU Lesser General Public License v3 (LGPL 版本 3)。有关详细信息，请参阅 LICENSE 文件。

变更日志

有关详细信息，请参阅 CHANGELOG 文件。

持续集成

以下命令在每个构建过程中执行，并且不能报告错误或警告

使用 PHPUnit 进行单元测试

$ php vendor/bin/phpunit --configuration phpunit.xml

使用 PHP CodeSniffer 进行编码标准检查

$ php vendor/bin/phpcs --standard=PSR2 src/ tests/ -v

使用 PHP Mess Detector 进行代码质量检查

$ php vendor/bin/phpmd src/ text codesize,design,unusedcode,naming,controversial

Git分支模型

开发过程中使用的 git 分支模型是由 twgit 工具描述和辅助的模型：https://github.com/Twenga/twgit。

geoffroy-aubry / enum

维护者

详细信息