### [PHP 8 新特性实战：枚举和匹配表达式在项目中的应用](https://www.huociguo.com/article/78)

**Published:** 2026-07-08T16:08:00

**Author:** 米了

**Excerpt:** PHP 8 系列版本陆续引入了多项影响编码方式的新特性，其中枚举（Enum）和匹配表达式（Match Expression）的组合，正在成为现代 PHP 项目中处理有限状态集合、替代散落字符串常量与多层 if-else / switch 分

PHP 8 系列版本陆续引入了多项影响编码方式的新特性，其中枚举（Enum）和匹配表达式（Match Expression）的组合，正在成为现代 PHP 项目中处理有限状态集合、替代散落字符串常量与多层 if-else / switch 分支的主流范式。本文基于 PHP 官方手册，结合真实项目场景，梳理两者的语法、协作方式、落地案例与避坑要点。

## 一、版本与环境前提

使用本教程中的特性需要满足以下最低版本要求：

-   **Match 表达式**：PHP 8.0.0 起可用
-   **枚举类型**：PHP 8.1.0 起可用

> ⚠️ 在低于 8.1 的 PHP 环境中，枚举语法会在编译阶段直接报错，不存在运行时降级的可能。生产环境部署前应通过 `php -v`确认版本。

## 二、枚举：从字符串常量到类型安全

### 1\. 纯枚举与回退枚举

PHP 官网对枚举的定义是”在类和类常量之上的约束层，用于定义可能值的封闭集合类型”。按其是否绑定标量值，分为两类：

```php
// 纯枚举：仅代表自身，无底层值
enum Suit {
    case Hearts;
    case Diamonds;
    case Clubs;
    case Spades;
}

// 回退枚举：绑定 string 或 int 标量值
enum UserStatus: string {
    case Pending = 'P';
    case Active = 'A';
    case Suspended = 'S';
    case CanceledByUser = 'C';
}
```

纯枚举适合内存中的状态标记；回退枚举适合需要持久化到数据库、通过 API 传输的场景，因为其标量值可以稳定存储。

### 2\. 枚举上的方法

枚举可以定义方法，也可以实现接口。这意味着与某个状态相关的业务逻辑可以直接内聚到枚举内部，而不是散落在控制器、服务类的各处。

```php
enum UserStatus: string implements HasLabel {
    case Pending = 'P';
    case Active = 'A';
    case Suspended = 'S';
    case CanceledByUser = 'C';

    public function label(): string {
        return match($this) {
            self::Pending => 'Pending',
            self::Active => 'Active',
            self::Suspended => 'Suspended',
            self::CanceledByUser => 'Canceled by user',
        };
    }
}
```

这里已经可以看到枚举与匹配表达式协作的第一个雏形——用 `match($this)`把”状态 → 文案”的映射集中在一处。

## 三、匹配表达式：严格比较的安全分支

### 1\. 核心差异

Match 表达式与 switch 语句在结构上相似，但存在三个关键差异：

|     |     |     |
| --- | --- | --- |  
| 维度  | switch 语句 | match 表达式 |
| 比较方式 | 松散比较 `==` | 严格比较 `===` |
| 返回值 | 需显式 `return`或赋值 | 表达式本身求值并返回 |
| 分支穿透 | 缺少 `break`会穿透 | 不会穿透 |
| 未匹配行为 | 静默跳过 | 抛出 `UnhandledMatchError` |

### 2\. 穷尽性约束

Match 表达式必须是穷尽的——如果主体表达式未被任何分支处理，将抛出 `UnhandledMatchError`。结合枚举使用时，这一特性可以在编译阶段发现”漏写分支”的问题。

### 3\. 多值与表达式匹配

一个分支可以匹配多个值（逗号分隔，相当于逻辑或），也可以用 `true`作为主体表达式来实现区间、正则等非恒等判断：

```php
$httpCode = 404;
$message = match ($httpCode) {
    200, 201 => '成功',
    400, 401, 403 => '客户端错误',
    404, 500 => '服务器错误',
    default => '未知状态码'
};
```

## 四、枚举与匹配表达式的协同实战

### 1\. 订单状态流转

订单状态是最典型的”有限集合 + 行为内聚”场景。用回退枚举承载数据库存储值，用匹配表达式承载状态转移逻辑：

```php
enum OrderStatus: string {
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    // 是否允许取消
    public function canBeCancelled(): bool {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Delivered, self::Cancelled => false,
        };
    }

    // 下一个状态
    public function next(): ?self {
        return match($this) {
            self::Pending => self::Paid,
            self::Paid => self::Shipped,
            self::Shipped => self::Delivered,
            self::Delivered, self::Cancelled => null,
        };
    }
}
```

业务代码中只需调用 `$order->status->canBeCancelled()`，无需在任何地方维护一张独立的状态转移表。

### 2\. API 响应状态码

将 HTTP 状态码封装为枚举，对外输出时统一走 `->value`，可避免魔法数字在代码中散落：

```php
enum ApiResponseStatus: int {
    case SUCCESS = 200;
    case VALIDATION_ERROR = 422;
    case NOT_FOUND = 404;
    case SERVER_ERROR = 500;

    public function message(): string {
        return match($this) {
            self::SUCCESS => '请求成功',
            self::VALIDATION_ERROR => '参数校验失败',
            self::NOT_FOUND => '资源不存在',
            self::SERVER_ERROR => '服务器内部错误',
        };
    }
}

// 控制器中
return response()->json([
    'status' => ApiResponseStatus::SUCCESS->value,
    'message' => ApiResponseStatus::SUCCESS->message(),
], ApiResponseStatus::SUCCESS->value);
```

### 3\. 支付渠道工厂

匹配表达式作为简单工厂的分支分发器，比一长串 `if-elseif`或 `switch-case-break`更紧凑：

```php
$driver = $_ENV['PAYMENT_DRIVER'] ?? 'alipay';

$gateway = match ($driver) {
    'alipay', 'alipay_mobile' => new AlipayGateway(),
    'wechat', 'wechat_h5' => new WechatPayGateway(),
    'unionpay' => new UnionPayGateway(),
    default => throw new InvalidArgumentException("不支持的支付渠道: $driver"),
};
```

## 五、序列化的边界与兼容处理

枚举的序列化行为与普通对象不同，需要特别注意：

-   反序列化时，PHP 通过枚举名定位已有的单例实例，保证 `Suit::Hearts === unserialize(serialize(Suit::Hearts))`
-   **纯枚举**直接 `json_encode`会抛出异常
-   **回退枚举**​ `json_encode`默认只输出其标量值（如 `"pending"`），不带类名
-   如需自定义 JSON 输出结构，可实现 `JsonSerializable`接口

对外接口（API 响应、消息队列载荷、缓存值）应始终输出 `->value`标量值，入参解析统一使用 `tryFrom()`而非 `from()`，前者在非法输入时返回 `null`而非抛出 `ValueError`。

## 六、常见

1.  **用字符串比较替代枚举比较**：`$order->status->value === 'pending'`会丢失类型安全，应直接用 `$order->status === OrderStatus::Pending`。
    
2.  **纯枚举用于持久化**：纯枚举没有标量值，无法直接存入数据库，需要持久化的场景必须使用回退枚举。
    
3.  **忽略 Match 的穷尽性**：枚举新增 case 后，未覆盖该 case 的 match 表达式会在运行时抛出 `UnhandledMatchError`，建议为关键分支增加 `default`兜底。
    
4.  **在数组键或 in\_array 中直接使用枚举实例**：`in_array('pending', Status::cases())`永远为 `false`，因为 `cases()`返回的是枚举实例数组，应使用 `Status::values()`获取底层值数组。
    
5.  **枚举继承**：枚举不能被 `extends`，但可以 `implements`接口、使用 trait，设计时应通过接口抽象共享契约。

**Tags:** Match 表达式, PHP 8, PHP 8.1 新特性, PHP 枚举, 后端开发

**Categories:** PHP教程

---