README

PHP常量作为枚举。

安装和文档

• 作为Composer包eloquent/constance可用。
• API文档可用。

什么是Constance？

Constance是一个库，用于将PHP常量表示为枚举类型。 Constance支持类级别和全局常量，并基于强大的枚举库提供丰富的功能集。

在其它用途中，Constance允许开发者

• 为预定义的常量集合中的有效值提供类型提示。例如，PHP错误级别和PDO属性。
• 从常量的值中检索有关常量的信息，例如其名称（对日志记录和调试很有用）。
• 使用位运算对常量集合进行简单操作，包括通过位掩码检索成员，或从成员数组中组合位掩码。

Constance在处理开发者无法控制的预定义常量时非常有用。如果开发者可以控制实现一等枚举，则建议直接使用枚举库。

实现常量枚举

Constance不提供任何具体类，而是提供抽象基类以使常量枚举的实现变得极其简单。有两个抽象基类 - AbstractClassConstant用于类级别常量，AbstractGlobalConstant用于全局常量。

类级别常量

此示例演示了如何定义PDO属性枚举

use Eloquent\Constance\AbstractClassConstant;

final class PdoAttribute extends AbstractClassConstant
{
    /**
     * The class to inspect for constants.
     */
    const CONSTANCE_CLASS = 'PDO';

    /**
     * The expression used to match constant names that should be included in
     * this enumeration.
     */
    const CONSTANCE_PATTERN = '{^ATTR_}';
}

正如示例所示，Constance枚举的实现非常简单。常量CONSTANCE_CLASS告诉Constance要检查哪个类中的常量，可选常量CONSTANCE_PATTERN是一个正则表达式，用于限制在CONSTANCE_CLASS中定义的哪些常量作为此枚举的成员。在这种情况下，表达式限制了成员为以ATTR_开头的常量。

现在可以使用此枚举在运行时只知道其值的情况下检索PDO属性常量的信息

$attribute = PdoAttribute::memberByValue(PDO::ATTR_ERRMODE);

echo $attribute->name();          // outputs 'ATTR_ERRMODE'
echo $attribute->qualifiedName(); // outputs 'PDO::ATTR_ERRMODE'

PdoAttribute也可以用作类型提示，它只接受有效的PDO属性。注意枚举成员访问的特殊静态调用语法

class MyConnection
{
    public function setAttribute(PdoAttribute $attribute, $value)
    {
        // ...
    }
}

$connection = new MyConnection;
$connection->setAttribute(PdoAttribute::ATTR_AUTOCOMMIT(), true);
$connection->setAttribute(PdoAttribute::ATTR_PERSISTENT(), false);

全局常量

本例演示了如何定义一个PHP错误级别枚举。

use Eloquent\Constance\AbstractGlobalConstant;

final class ErrorLevel extends AbstractGlobalConstant
{
    /**
     * The expression used to match constant names that should be included in
     * this enumeration.
     */
    const CONSTANCE_PATTERN = '{^E_}';
}

全局常量比类级别常量更简单易用。可选常量CONSTANCE_PATTERN是一个正则表达式，用于限制哪些全局定义的常量被定义为该枚举的成员。在本例中，该表达式限制了成员为以E_开头的常量。

上述枚举将包含所有定义的PHP错误级别常量的成员，例如E_NOTICE、E_WARNING、E_ERROR、E_ALL和E_STRICT。注意，Constance提供了一些有限的位运算辅助方法，用于处理此类具有位运算值的常量集合，这将在单独的章节中讨论。

位运算逻辑

Constance提供了一些方法来处理具有位运算值的常量集合。上述PHP错误级别枚举就是一个很好的例子。

假设上述描述的ErrorLevel枚举，可以如此确定包含在E_ALL中的成员集合

$members = ErrorLevel::membersByBitmask(E_ALL);

$members现在包含一个数组，表示当前运行时环境中包含在E_ALL中的所有错误级别。相反，也可以同样轻松地确定未包含的成员

$members = ErrorLevel::membersExcludedByBitmask(E_ALL);

也可以为任意枚举成员集生成位掩码，如下所示

$members = array(ErrorLevel::E_NOTICE(), ErrorLevel::E_DEPRECATED());
$bitmask = ErrorLevel::membersToBitmask($members);

$bitmask现在包含一个位掩码，仅匹配E_NOTICE或E_DEPRECATED。

最后，检查给定的枚举成员是否匹配位掩码也非常简单

$isStrictByDefault = ErrorLevel::E_STRICT()->valueMatchesBitmask(E_ALL);

$isStrictByDefault现在将包含一个布尔值，表示E_ALL是否包含当前运行时环境的严格标准警告。