PHP 8.1+ 枚举：获取所有成员名称与值方法

PHP 8.1+ 枚举基础与 cases() 方法

PHP 8.1引入了对枚举（Enums）的原生支持，为定义一组有限的、命名常量集合提供了更结构化和类型安全的方式。每个枚举成员都是一个UnitEnum实例。枚举类型提供了一个核心方法 cases()，它返回一个包含所有枚举成员实例的数组。

例如，定义一个简单的基本枚举：

enum Status
{
    case Active;
    case Inactive;
    case Pending;
}

调用 Status::cases() 将返回 [Status::Active, Status::Inactive, Status::Pending]。

获取枚举成员名称

无论是基本枚举（Unit Enum）还是支持枚举（Backed Enum），都可以通过访问其name属性来获取成员的名称。结合cases()方法和array_column函数，可以轻松获取所有成员的名称数组。

enum Suit
{
    case Hearts;
    case Diamonds;
    case Clubs;
    case Spades;
}

// 获取所有枚举成员的名称
$suitNames = array_column(Suit::cases(), 'name');

print_r($suitNames);
/* 输出:
Array
(
    [0] => Hearts
    [1] => Diamonds
    [2] => Clubs
    [3] => Spades
)
*/

获取支持枚举成员值 (Backed Enum Values)

支持枚举（Backed Enum）允许为每个成员关联一个标量值（字符串或整数）。对于这类枚举，除了名称外，我们还可以通过其value属性获取关联的值。

enum Color: string
{
    case Red = 'R';
    case Green = 'G';
    case Blue = 'B';
}

// 获取所有支持枚举成员的关联值
$colorValues = array_column(Color::cases(), 'value');

print_r($colorValues);
/* 输出:
Array
(
    [0] => R
    [1] => G
    [2] => B
)
*/

构建可复用的 EnumToArray Trait

为了避免在每个枚举中重复编写获取名称和值的逻辑，我们可以创建一个Trait来封装这些常用操作。这个Trait将提供names()、values()和array()等静态方法，方便地获取枚举的各种表示形式。

以下是EnumToArray Trait的定义：

trait EnumToArray
{
    /**
     * 获取所有枚举成员的名称数组。
     * 例如：['Hearts', 'Diamonds']
     *
     * @return array
     */
    public static function names(): array
    {
        return array_column(self::cases(), 'name');
    }

    /**
     * 获取所有支持枚举成员的关联值数组。
     * 仅适用于 Backed Enum。
     * 例如：['H', 'D']
     *
     * @return array
     */
    public static function values(): array
    {
        // 检查当前枚举是否为 Backed Enum
        if (!is_subclass_of(self::class, \BackedEnum::class)) {
            throw new \BadMethodCallException(sprintf('The method %s::values() can only be called on Backed Enums.', self::class));
        }
        return array_column(self::cases(), 'value');
    }

    /**
     * 获取一个将关联值映射到名称的数组。
     * 仅适用于 Backed Enum。
     * 例如：['H' => 'Hearts', 'D' => 'Diamonds']
     *
     * @return array
     */
    public static function array(): array
    {
        // 检查当前枚举是否为 Backed Enum
        if (!is_subclass_of(self::class, \BackedEnum::class)) {
            throw new \BadMethodCallException(sprintf('The method %s::array() can only be called on Backed Enums.', self::class));
        }
        return array_combine(self::values(), self::names());
    }
}

注意事项：

• values()和array()方法中增加了运行时检查，确保它们只在支持枚举（Backed Enum）上调用，否则会抛出BadMethodCallException，提高了代码的健壮性。
• array()方法将value作为键，name作为值，生成一个映射数组。

在枚举中使用 EnumToArray Trait

要使用这个Trait，只需在你的枚举定义中引入它即可。

enum Suit: string
{
    use EnumToArray; // 引入 Trait

    case Hearts = 'H';
    case Diamonds = 'D';
    case Clubs = 'C';
    case Spades = 'S';
}

// 使用 Trait 提供的方法
$suitNames = Suit::names();
$suitValues = Suit::values();
$suitMap = Suit::array();

echo "所有名称: \n";
print_r($suitNames);
/* 输出:
所有名称:
Array
(
    [0] => Hearts
    [1] => Diamonds
    [2] => Clubs
    [3] => Spades
)
*/

echo "\n所有值: \n";
print_r($suitValues);
/* 输出:
所有值:
Array
(
    [0] => H
    [1] => D
    [2] => C
    [3] => S
)
*/

echo "\n值到名称的映射: \n";
print_r($suitMap);
/* 输出:
值到名称的映射:
Array
(
    [H] => Hearts
    [D] => Diamonds
    [C] => Clubs
    [S] => Spades
)
*/

通过EnumToArray Trait，我们为枚举提供了一套标准化的接口，用于获取其成员的各种表示形式，极大地简化了代码并提高了可维护性。

总结与注意事项

• cases() 方法核心： 它是获取所有枚举成员实例的入口，是所有进一步操作的基础。
• array_column 的灵活性： array_column 函数是处理cases()返回数组的关键，通过指定'name'或'value'作为第二个参数，可以高效地提取所需的数据。
• Trait 的优势： 使用Trait能够将通用的逻辑封装起来，避免代码重复，使得枚举定义更简洁，同时易于扩展和维护。
• 区分基本枚举与支持枚举： 只有支持枚举（Backed Enum）才具有value属性。在使用values()或array()方法时，务必确保你的枚举是支持枚举类型，或者像示例Trait中那样加入类型检查以增强健壮性。
• PHP 版本要求： 本教程中介绍的枚举功能及cases()方法仅适用于 PHP 8.1 及更高版本。

掌握这些方法，将使你在PHP 8.1+项目中能够更高效、更优雅地处理枚举数据。