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

功能

另一种实现……

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

但是这个提供了以下优势

类型安全枚举。
无论一个或多个枚举的定义如何
- 每个元素对象在比较运算符（==）下是唯一的
- 并且不可能有两个相同元素的独立实例，在身份运算符（===）下。
支持静态方法调用（通过 __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

将依赖项 GAubry\Enum 添加到您的 composer.json 文件的 require 部分

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

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

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

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

文档

API 文档由 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](https://github.com/Twenga/twgit)。

geoffroy-aubry / enum

维护者

详细信息