README

FlorianWolters\Component\Core\Enum是一个简单易用的PHP组件，提供了安全枚举模式。

简介

PHP脚本语言缺少一个重要的数据类型：枚举类型。

今天，随着PHP脚本语言5.4版本的推出，仍然没有对枚举类型的语言支持。只有一个从2010-05-21)提出的请求评论(RFC)，建议添加枚举语言结构。

许多编程语言，例如Pascal、Modula-2、Modula-3、Ada、Haskell、C、C++和C#都有枚举类型。例如，Java通过对象实现了枚举类型（参见Java教程和Java API文档）。

可以在PHP中使用int枚举模式来表示枚举类型

<?php
public const SEASON_WINTER = 0;
public const SEASON_SPRING = 1;
public const SEASON_SUMMER = 2;
public const SEASON_FALL = 3;

int枚举模式有许多（严重的）问题，例如

不安全 - 由于季节只是一个int，你可以将任何其他int值传递到需要季节的地方，或者将两个季节相加（这是没有意义的）。

没有命名空间 - 你必须使用字符串（在这种情况下为SEASON_）前缀int枚举的常量，以避免与其他int枚举类型冲突。

脆弱 - 因为int枚举是编译时常量，它们被编译进使用它们的客户端。如果在两个现有常量之间添加了新常量或改变了顺序，客户端必须重新编译。如果不这样做，它们仍然可以运行，但它们的行性行为将是未定义的。

打印的值没有信息 - 因为它们只是ints，如果你打印出一个，你只会得到一个数字，这告诉你什么都没有，甚至不知道它代表什么，或是什么类型。

可以通过使用安全枚举模式来解决这个问题（参见有效的Java第21项）。这个模式也有它自己的问题：它相当冗长，因此容易出错，并且它的枚举常量不能在switch语句中使用。

(cf. Oracle. Enums)

动机

由于PHP中没有枚举类型，我决定创建自己的实现。

我的解决方案实现了安全枚举模式。这个模式已经被适应和抽象化，以适应PHP。因此，我的实现没有原始安全枚举模式的问题（见上面的简介）

枚举常量可以在switch语句中使用（Java 1.5中不可能做到这一点）。
与原始实现相比，它不那么冗长（见下文使用方法），因此出错的可能性更小。

特性

抽象枚举基类实现了Typesafe Enum（参见Effective Java第21项）模式。
支持在集成开发环境（IDE）中自动完成。
支持函数式枚举。这意味着可以在枚举常量上使用操作（方法调用）。
枚举类可以扩展另一个枚举类，因此可以构建枚举层次结构。
枚举常量可以通过serialize()和unserialize()函数进行序列化和反序列化。
枚举类可以放在命名空间中，因此可以避免命名冲突。
每个枚举常量都是一个对象，它是
- 一个Singleton，更确切地说是一个Multiton（参见《设计模式：可重用面向对象软件的元素》第3项），以及一个不可变值对象。这意味着每个枚举常量都只由一个实例表示，比较是基于枚举常量的名称。

枚举常量不能通过魔法__clone方法进行克隆。

对静态和动态测试程序进行测试的工件

使用PHPUnit实现的动态组件测试（单元测试）。
- 使用以下工具执行静态代码分析
- PHP_CodeSniffer：样式检查器
  - PHP Mess Detector (PHPMD)：代码分析器
  - phpcpd：复制/粘贴检测器（CPD）
  - phpdcd：死代码检测器（DCD）
  - 通过Composer或PEAR安装程序安装
提供了一个Packagist软件包，可以使用依赖管理器Composer进行安装。
- 提供了一个Packagist软件包，可以使用依赖管理器Composer进行安装。
  - 点击Packagist上的此处。
- 提供了一个PEAR软件包，可以使用软件包管理器PEAR安装程序进行安装。
  - 点击此处以访问PEAR通道。
提供了一个使用文档生成器ApiGen生成的完整应用程序编程接口（API）文档。
- 点击此处以访问当前的API文档。
遵循自动加载器互操作性的PSR-0要求。
遵循PSR-1基本编码风格指南。
遵循PSR-2编码风格指南。
遵循语义版本规范（SemVer）2.0.0-rc.1。

FlorianWolters\Component\Core\Enum 不（并且不会）具备以下功能

枚举类的生成。
对PHP版本 <= 5.4 的支持。

要求

使用

最重要的使用规则

始终将获取枚举常量的方法声明为final public static，并将方法名称写成大写字母。

在使用FlorianWolters\Component\Core\Enum时，应遵循以下最佳实践

除非枚举类应由另一个枚举类扩展，否则始终将枚举类声明为final。
始终在每个获取枚举常量的方法中添加一个带有枚举类名称的DocBlock标签@return。这将在集成开发环境（IDE）中启用自动完成。
始终将后缀Enum添加到表示枚举类型的类的名称中。这与在PSR-2中描述的接口和抽象类的命名约定类似。

以下资源包含更多信息

点击这里访问FlorianWolters\Component\Core\Enum的Wiki。Wiki的使用部分包含多个已记录的源代码示例。
点击这里访问FlorianWolters\Component\Core\Enum的API文档。

安装

本地安装

应使用依赖管理器Composer安装FlorianWolters\Component\Core\Enum。可以使用PHP安装Composer。

php -r "eval('?>'.file_get_contents('http://getcomposer.org/installer'));"

这将检查一些PHP设置，然后将composer.phar下载到您的当前工作目录。此文件是Composer的二进制文件。它是一个PHAR（PHP存档），是一种PHP存档格式，可以在命令行中运行，以及其他一些用途。

接下来，运行install命令以解析和下载依赖项

php composer.phar install

全局安装

应使用PEAR安装程序安装FlorianWolters\Component\Core\Enum。此安装程序是PHP社区为安装PHP组件的既定标准。

pear channel-discover http://pear.florianwolters.de
pear install --alldeps fw/Enum

作为组件依赖

Composer

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

{
    "require": {
        "florianwolters/component-core-enum": "0.4.*"
    }
}

PEAR

如果您正在创建一个依赖 FlorianWolters\Component\Core\Enum 的组件，请确保将 FlorianWolters\Component\Core\Enum 添加到组件的 package.xml 文件中

<dependencies>
  <required>
    <package>
      <name>Enum</name>
      <channel>http://pear.florianwolters.de</channel>
      <min>0.4.0</min>
      <max>0.4.99</max>
    </package>
  </required>
</dependencies>

开发环境

如果您想对该组件进行修补或增强，您需要创建一个合适的发展环境。最简单的方法是安装 phix4componentdev

# phix4componentdev
pear channel-discover pear.phix-project.org
pear install phix/phix4componentdev

然后，克隆 Git 仓库

# PHP-Component-Core-Enum
git clone https://github.com/florianwolters/PHP-Component-Core-Enum

然后，安装该组件依赖的本地副本以完成开发环境

# build vendor/ folder
phing build-vendor

为了使您的生活更轻松，常用的任务（例如运行单元测试、生成代码审查分析以及创建 PEAR 软件包）已通过 phing 自动化。您可以在组件附带的 build.xml 文件中找到这些自动化步骤。

在组件的顶级文件夹中运行 phing 命令以查看可用的完整自动化任务列表。

许可

本程序是免费软件：您可以按照自由软件基金会发布的 GNU 较小通用公共许可证的条款重新分发和/或修改它，许可证版本为 3 或（根据您选择）更高版本。

本程序分发时希望对您有用，但没有任何保证；甚至没有关于其可销售性或适合特定用途的暗示保证。有关详细信息，请参阅 GNU 较小通用公共许可证。

您应已收到随此程序一起提供的 GNU 较小通用公共许可证副本。如果没有，请参阅 http://gnu.org/licenses/lgpl.txt。

florianwolters / component-core-enum

维护者

详细信息