PHP 枚举（Enum）、只读属性与新特性完整解析-php教程-PHP中文网

PHP 8.1+ 枚举不支持实例方法和属性，仅允许静态方法与常量；readonly 属性仅禁止二次赋值，不保证对象完全不可变；readonly class 是语法糖，不替代输入校验；枚举 match 无穷尽性检查，需人工或工具保障完整性。

php 枚举（enum）、只读属性与新特性完整解析

PHP 8.1+ 的 `enum` 不支持方法体，但可以带静态方法和常量

PHP 的枚举不是“类的简化版”，它本质是受限的值类型，编译期就固化了可选值。你不能在 enum 中写普通实例方法（比如 ->getName()），也不能定义属性（$value 或 $label 这类），更不能用 __construct() 初始化。

但你可以用静态方法模拟行为：

enum Status: string
{
    case Draft = 'draft';
    case Published = 'published';

    public static function fromLabel(string $label): self
    {
        return match ($label) {
            '草稿' => self::Draft,
            '已发布' => self::Published,
            default => throw new ValueError("Unknown label: $label"),
        };
    }
}

常见错误：试图给枚举加 public function getLabel(): string —— PHP 会报 ParseError: Enum cases cannot have methods。正确做法是把逻辑移到静态方法或外部工具类里。

枚举的 backed 类型（string 或 int）必须显式声明，否则无法用 ->value 或 ::from()
未声明 backing type 的 pure enum 只能用 match 或 match + self::cases() 做值映射
Status::Draft->value 是合法的，但 Status::Draft->name 不存在 —— 名字只能通过反射或硬编码获取

`readonly` 属性只在构造后禁止修改，不等于“不可变对象”

readonly 修饰的是属性本身，不是整个对象。只要属性没被标记为 readonly，它依然可写；哪怕所有属性都是 readonly，你仍能调用非 readonly 方法改变内部状态（比如缓存、计数器）。

典型误用场景：

class User
{
    public readonly string $id;
    public readonly string $name;

    public function __construct(string $id, string $name)
    {
        $this->id = $id;
        $this->name = $name;
    }

    public function rename(string $newName): void
    {
        $this->name = $newName; // ⚠️ Fatal error: Cannot modify readonly property
    }
}

关键点：

readonly 属性只能在构造函数中赋值一次，之后任何写入（包括反射、__set、序列化还原）都会触发 Fatal error
数组或对象类型的 readonly 属性，其内部数据仍可变（例如 public readonly array $tags; → $user->tags[] = 'admin'; 合法）
要真正冻结结构，得配合 array_values()、ImmutableArray 类或第三方库（如 spatie/immutable-array）

PHP 8.2 的 `readonly` 类仍需手动控制构造逻辑

readonly class 是语法糖，它自动把所有属性设为 readonly，但不会帮你校验参数、阻止重复初始化，也不会隐式调用 __construct() —— 它只是批量加 readonly，仅此而已。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

下面这段代码看似安全，实则漏洞明显：

readonly class Config
{
    public function __construct(
        public string $host,
        public int $port,
    ) {}
}

$config = new Config('localhost', 8080);
$config->host = 'evil.com'; // ⚠️ Fatal error —— 没问题
// 但没人阻止你传入空字符串或非法端口
$config = new Config('', -1); // ✅ 合法，但语义错误

所以你仍得自己加约束：

在构造函数里抛出 InvalidArgumentException 校验输入
避免在 readonly class 中定义可变依赖（如 public PDO $db;），因为连接对象本身状态可变
不要指望 readonly class 能替代 DTO 验证层 —— 它只管“写一次”，不管“写得对不对”

枚举 + 只读类组合使用时，注意 `match` 表达式的穷尽性检查缺失

PHP 不做枚举 match 的编译期穷尽性检查。即使你新增了一个 case，旧的 match 也不会报错或警告，运行时直接掉进 default 分支 —— 这是实际项目中最容易漏掉的逻辑缺口。

比如：

enum PaymentMethod: string
{
    case CreditCard = 'card';
    case BankTransfer = 'bank';
}

function feeRate(PaymentMethod $method): float
{
    return match ($method) {
        PaymentMethod::CreditCard => 0.029,
        PaymentMethod::BankTransfer => 0.005,
        // 新增 PayPal 后这里没更新 → 默认返回 0.0
        default => 0.0,
    };
}

解决办法有限：