PHP 枚举 Enumerations

本页内容

什么是枚举

[1]

PHP 8 中新增加的特性,枚举,或称 “Enum”,能够让开发者自定义类型为一系列可能的离散值中的一个。 在定义领域模型中很有用,它能够“隔离无效状态”(making invalid states unrepresentable)。

枚举以各种不同功能的形式出现在诸多语言中。 在 PHP 中, 枚举是一种特殊类型的对象。Enum 本身是一个类(Class), 它的各种条目(case)是这个类的单例对象,意味着也是个有效对象 —— 包括类型的检测,能用对象的地方,也可以用它。

最常见的枚举例子是内置的 boolean 类型, 该枚举类型有两个有效值 true 和 false。 Enum 使开发者能够任意定义出用户自己的、足够健壮的枚举。

枚举基础

Enum 类似 class,它和 class、interface、trait 共享同样的命名空间。 也能用同样的方式自动加载。 一个 Enum 定义了一种新的类型,它有固定、数量有限、可能的合法值。

示例

<?php
enum Suit
{
    case Hearts;
    case Diamonds;
    case Clubs;
    case Spades;
}
?>

以上声明了新的枚举类型 Suit,仅有四个有效的值: Suit::Hearts、Suit::Diamonds、 Suit::Clubs、Suit::Spades。 变量可以赋值为以上有效值里的其中一个。 函数可以检测枚举类型,这种情况下只能传入类型的值。


示例

<?php
function pick_a_card(Suit $suit) { ... }

$val = Suit::Diamonds;

// OK
pick_a_card($val);
// OK
pick_a_card(Suit::Clubs);
// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
?>

一个枚举可以定义零个或多个case,且没有最大数量限制。 虽然零个 case 的 enum 没什么用处,但在语法上也是有效的。

枚举条目的语法规则适用于 PHP 中的任何标签,参见常量。

默认情况下,枚举的条目(case)本质上不是标量。 就是说 Suit::Hearts 不等同于 "0"。 其实,本质上每个条目是该名称对象的单例。具体来说:


示例

<?php
$a = Suit::Spades;
$b = Suit::Spades;

$a === $b; // true

$a instanceof Suit;  // true
?>

由于对象间的大小比较毫无意义,这也意味着 enum 值从来不会 < 或 > 其他值。 当 enum 的值用于比较时,总是返回 false。

这类没有关联数据的条目(case),被称为“纯粹条目”(Pure Case)。 仅包含纯粹 Case 的 Enum 被称为纯粹枚举(Pure Enum)。

枚举类型里所有的纯粹条目都是自身的实例。 枚举类型在内部的实现形式是一个 class。

所有的 case 有个只读的属性 name。 它大小写敏感,是 case 自身的名称。


示例

<?php
print Suit::Spades->name;
// 输出 "Spades"
?>


回退(Backed)枚举

默认情况下枚举条目实现形式不是标量。 它们是纯粹的对象实例。 不过,很多时候也需要在数据库、数据存储对象中来回读写枚举条目。 因此,能够内置支持标量形式也很有用(更易序列化)。

按以下语法,定义标量形式的枚举:


示例

<?php
enum Suit: string
{
    case Hearts = 'H';
    case Diamonds = 'D';
    case Clubs = 'C';
    case Spades = 'S';
}
?>

由于有标量的条目回退(Backed)到一个更简单值,又叫回退条目(Backed Case)。 包含所有回退条目的 Enum 又叫“回退 Enum”(Backed Enum)。 回退 Enum 只能包含回退条目。 纯粹 Enum 只能包含纯粹条目。

回退枚举仅能回退到 int 或 string 里的一种类型, 且同时仅支持使用一种类型(就是说,不能联合 int|string)。 如果枚举为标量形式,所有的条目必须明确定义唯一的标量值。 无法自动生成标量(比如:连续的数字)。 回退条目必须是唯一的;两个回退条目不能有相同的标量。 然而,也可以用常量引用到条目,实际上是创建了个别名。 参见 枚举常量。

条目等同的值,必须是个字面量或它的表达式。 不能是常量和常量表达式。 换言之,允许 1 + 1, 不允许 1 + SOME_CONST。

回退条目有个额外的只读属性 value, 它是定义时指定的值。

示例

<?php
print Suit::Clubs->value;
// 输出 "C"
?>

为了确保 value 的只读性, 无法将变量传引用给它。 也就是说,以下会抛出错误:


示例

<?php
$suit = Suit::Clubs;
$ref = &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>

回退枚举实现了内置的 BackedEnum interface, 暴露了两个额外的方法:

from(int|string): self 能够根据标量返回对应的枚举条目。 如果找不到该值,会抛出 ValueError。 主要用于输入标量为可信的情况,使用一个不存在的枚举值,可以考虑为需终止应用的错误。 tryFrom(int|string): ?self 能够根据标量返回对应的枚举条目。 如果找不到该值,会返回 null。 主要用于输入标量不可信的情况,调用者需要自己实现默认值的逻辑或错误的处理。 from() 和 tryFrom() 方法也遵循基本的严格/松散类型规则。 系统在弱类型模式下接受传入 integer 和 string,并自动强制转换对应值。 传入 float 也能运行,并且强制转换。 在严格类型模式下,为 string 回退枚举的 from() 传入 integer 会导致 TypeError,反之亦然;float 都会出现有问题。 其他所有的参数类型,在以上所有模式中都会抛出 TypeError。


示例

<?php
$record = get_stuff_from_database($id);
print $record['suit'];

$suit =  Suit::from($record['suit']);
// 无效数据抛出 ValueError:"X" is not a valid scalar value for enum "Suit"
print $suit->value;

$suit = Suit::tryFrom('A') ?? Suit::Spades;
// 无效数据返回 null,因此会用 Suit::Spades 代替。
print $suit->value;
?>

手动为回退枚举定义 from() 或 tryFrom() 方法会导致 fatal 错误。

此页面最后编辑于2022年10月28日 (星期五) 14:39。