本教程详细介绍了在 php 8.1 及更高版本中如何高效地获取枚举（enum）的所有成员名称和支持值（backed values）。文章首先阐述了通过 cases() 方法结合 array_column 获取基本名称和支持值的方法，随后深入探讨了如何利用 trait 模式构建可复用的功能，以实现枚举名称、支持值列表以及键值对映射的自动化管理，从而提升代码的整洁性和可维护性。
PHP 8.1 引入了对枚举（Enums）的原生支持，为开发者提供了一种定义一组有限、命名值集合的强大方式。在实际开发中，经常需要获取枚举的所有成员名称或其关联的支持值。本文将详细介绍如何在 PHP 8.1 及更高版本中实现这一目标，并提供一种利用 Trait 模式进行高级管理的方法。
基础枚举值获取
PHP 的枚举提供了一个静态方法 cases()，它返回一个包含所有枚举成员实例的数组。每个实例都是一个 UnitEnum 或 BackedEnum 的对象，它们都拥有 name 属性，而 BackedEnum 额外拥有 value 属性。
获取枚举成员名称
对于任何类型的枚举，我们都可以通过 cases() 方法获取所有成员的名称。name 属性返回枚举成员的声明名称（例如 Hearts）。结合 array_column 函数，可以轻松提取所有名称。
<?php
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）的值
当枚举是支持值枚举（Backed Enum）时，每个成员除了名称外，还关联了一个具体的值（例如字符串或整数）。我们可以使用 value 属性来获取这些支持值。
立即学习“PHP免费学习笔记（深入）”；
<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
// 获取所有支持值枚举成员的值
$suitValues = array_column(Suit::cases(), 'value');
print_r($suitValues);
/*
Array
(
[0] => H
[1] => D
[2] => C
[3] => S
)
*/
?>高级应用：使用 Trait 增强枚举功能
为了避免在每个枚举中重复编写获取名称和值的逻辑，我们可以利用 PHP 的 Trait 特性来封装这些常用功能。通过创建一个 EnumToArray Trait，可以为任何枚举提供便捷的方法来获取其名称、值列表，甚至是一个键值对映射。
EnumToArray Trait 的实现
以下是一个 EnumToArray Trait 的示例，它提供了三个静态方法：names()、values() 和 array()。
<?php
trait EnumToArray
{
/**
* 获取所有枚举成员的名称数组。
* 适用于所有枚举类型。
*
* @return array
*/
public static function names(): array
{
return array_column(self::cases(), 'name');
}
/**
* 获取所有支持值枚举成员的值数组。
* 仅适用于 Backed Enum。
*
* @return array
* @throws BadMethodCallException 如果当前枚举不是 Backed Enum
*/
public static function values(): array
{
// 确保是 Backed Enum，否则 'value' 属性不存在
if (!is_subclass_of(static::class, \BackedEnum::class)) {
throw new \BadMethodCallException(static::class . ' is not a Backed Enum.');
}
return array_column(self::cases(), 'value');
}
/**
* 获取一个将支持值映射到名称的关联数组。
* 仅适用于 Backed Enum。
*
* @return array
* @throws BadMethodCallException 如果当前枚举不是 Backed Enum
*/
public static function array(): array
{
// 确保是 Backed Enum
if (!is_subclass_of(static::class, \BackedEnum::class)) {
throw new \BadMethodCallException(static::class . ' is not a Backed Enum.');
}
return array_combine(self::values(), self::names());
}
}
?>代码说明：
- names()：使用 array_column 提取所有枚举成员的 name 属性。
- values()：同样使用 array_column 提取所有枚举成员的 value 属性。这里加入了类型检查，确保只有 BackedEnum 才能调用此方法，否则会抛出异常。
- array()：结合 values() 和 names()，使用 array_combine 创建一个关联数组，其中键是枚举的支持值，值是枚举成员的名称。同样进行了类型检查。
在枚举中使用 Trait
现在，我们可以将 EnumToArray Trait 应用到任何需要这些功能的枚举中。
<?php
// 引入上面定义的 EnumToArray Trait
// require_once 'EnumToArray.php'; // 实际项目中可能需要引入 Trait 文件
enum Suit: string
{
use EnumToArray; // 使用 Trait
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
// 使用 Trait 提供的方法
$suitNames = Suit::names();
print_r($suitNames);
/*
Array
(
[0] => Hearts
[1] => Diamonds
[2] => Clubs
[3] => Spades
)
*/
$suitValues = Suit::values();
print_r($suitValues);
/*
Array
(
[0] => H
[1] => D
[2] => C
[3] => S
)
*/
$suitMap = Suit::array();
print_r($suitMap);
/*
Array
(
[H] => Hearts
[D] => Diamonds
[C] => Clubs
[S] => Spades
)
*/
// 尝试在非 Backed Enum 上调用 values() 或 array() 会抛出异常
/*
enum Color { use EnumToArray; case Red; }
try {
Color::values();
} catch (\BadMethodCallException $e) {
echo "Error: " . $e->getMessage() . "\n";
}
// Output: Error: Color is not a Backed Enum.
*/
?>通过这种方式，我们不仅能够轻松获取枚举的各种数据，还保持了枚举定义的简洁性，并通过 Trait 实现了功能的复用。
注意事项
- PHP 版本要求: 枚举功能自 PHP 8.1 起可用。请确保您的 PHP 环境满足版本要求。
- cases() 返回值: cases() 方法返回的是 EnumCase 对象的数组，而不是简单的字符串或整数数组。array_column 的第二个参数 'name' 或 'value' 是访问这些对象属性的关键。
- value 属性: value 属性只存在于 BackedEnum（支持值枚举）的实例中。尝试在非 BackedEnum 上访问 value 属性会导致运行时错误或返回 null。在 Trait 中进行类型检查是良好的实践，可以提供更清晰的错误信息。
- Trait 的复用性: EnumToArray Trait 可以被任何需要类似功能的枚举复用，避免了代码冗余，提高了代码的可维护性。
总结
PHP 8.1 引入的枚举功能极大地提升了代码的清晰度和类型安全性。通过 cases() 方法结合 array_column，我们可以方便地获取枚举的所有成员名称和支持值。进一步地，利用 Trait 模式可以封装这些常用操作，创建出更具扩展性和维护性的枚举管理方案。掌握这些技巧，将有助于您在 PHP 项目中更高效、更优雅地使用枚举。
