Enum trong PHP: backed enum, from(), tryFrom() và cases()

Enum trong PHP (PHP 8.1+) định nghĩa một kiểu với tập giá trị cố định, gọi là các case: enum Status { case Active; case Banned; }. Bạn dùng một case dưới dạng Status::Active, và tham số có kiểu Status sẽ không nhận gì khác. Backed enum, enum Status: string, còn gán cho mỗi case một giá trị mà bạn có thể lưu lại và chuyển ngược về bằng Status::from().

<?php
enum Status: string
{
    case Active = 'active';
    case Pending = 'pending';
    case Banned = 'banned';
}

function canLogIn(Status $status): bool
{
    return $status === Status::Active;
}

$s = Status::Pending;
echo $s->name, ' = ', $s->value, "\n";
var_dump(canLogIn($s), canLogIn(Status::Active));

// From a value stored in a database or a form
$fromDb = Status::from('banned');
echo $fromDb->name, "\n";

Trước khi có enum, việc này là một danh sách hằng số chuỗi, và không gì ngăn được một lỗi gõ như 'actve' lọt vào cơ sở dữ liệu. Khi tham số có kiểu Status, chỉ ba case kia mới truyền vào được.

Pure enum và backed enum

Pure enum có các case chỉ là tên. Backed enum khai báo một kiểu sau tên, int hoặc string, và khi đó mọi case đều phải có một giá trị duy nhất thuộc kiểu ấy. Mọi case đều có ->name; chỉ case của backed enum mới có ->value.

<?php
enum Suit
{
    case Hearts;
    case Spades;
}

enum Priority: int
{
    case Low = 1;
    case Normal = 5;
    case Urgent = 10;
}

$card = Suit::Hearts;
echo $card->name, "\n";
var_dump($card === Suit::Hearts, $card instanceof Suit);

$p = Priority::Urgent;
echo $p->name, ' = ', $p->value, "\n";
var_dump(Priority::Low->value < Priority::Urgent->value);
var_dump($p);

Hãy chọn backed enum mỗi khi giá trị đi ra khỏi chương trình: một cột cơ sở dữ liệu, một URL, một trường form, JSON. Chọn pure enum cho những giá trị chỉ tồn tại bên trong code, như trạng thái của một bộ phân tích cú pháp.

Chuyển đổi giá trị bằng from() và tryFrom()

Backed enum có hai phương thức tĩnh để biến một giá trị đã lưu trở lại thành case. from() ném ra ValueError với giá trị không xác định; tryFrom() trả về null, rất hợp khi đi cùng ?? để lấy giá trị mặc định:

<?php
enum Size: string
{
    case Small = 's';
    case Medium = 'm';
    case Large = 'l';
}

var_dump(Size::from('m'));
var_dump(Size::tryFrom('xl'));

$size = Size::tryFrom('xl') ?? Size::Medium;
echo "Using {$size->name}\n";

try {
    Size::from('xl');
} catch (ValueError $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Dùng tryFrom() cho mọi thứ người dùng gửi đến, và from() cho các giá trị do chính code của bạn ghi ra, nơi một giá trị lạ nghĩa là có bug mà bạn muốn biết. Đối số tuân theo quy tắc kiểu tham số thông thường: với enum kiểu int, ở chế độ mặc định Priority::from('5') trả về Priority::Normal vì '5' được chuyển thành 5 trước, Priority::from('5x') là TypeError, còn với declare(strict_types=1) thì mọi chuỗi đều là TypeError. Điều đó áp dụng cả cho tryFrom(): Priority::tryFrom('abc') ném ngoại lệ thay vì trả về null, nên hãy kiểm tra dữ liệu form cho enum kiểu int bằng filter_var($raw, FILTER_VALIDATE_INT) trước.

Liệt kê mọi case bằng cases()

Enum::cases() trả về một mảng gồm mọi case, theo thứ tự khai báo. Đây là cách bạn tạo dropdown, kiểm tra một danh sách, hoặc lấy mọi giá trị bằng array_column:

<?php
enum Plan: string
{
    case Free = 'free';
    case Pro = 'pro';
    case Team = 'team';

    public function label(): string
    {
        return match ($this) {
            Plan::Free => 'Free',
            Plan::Pro => 'Pro, 9 EUR a month',
            Plan::Team => 'Team, 29 EUR a month',
        };
    }
}

$chosen = Plan::tryFrom($_POST['plan'] ?? '');

echo '<form method="post"><select name="plan">';
foreach (Plan::cases() as $plan) {
    $selected = $plan === $chosen ? ' selected' : '';
    echo "<option value=\"{$plan->value}\"$selected>{$plan->label()}</option>";
}
echo '</select> <button>Choose</button></form>';

if ($chosen !== null) {
    echo "<p>You picked <b>{$chosen->name}</b> (stored as '{$chosen->value}').</p>";
}

echo '<pre>', implode(', ', array_column(Plan::cases(), 'value')), '</pre>';

Hãy chạy nó, chọn một gói và nhấn Choose: cùng script đó chạy lại với $_POST['plan'] đã có dữ liệu, và tryFrom() biến chuỗi được gửi lên trở lại thành một case của Plan. Một giá trị giả mạo như plan=gold cho ra null, và không có lựa chọn nào được chọn.

Phương thức, hằng số và interface của enum

Enum có thể có phương thức, phương thức tĩnh và hằng số, và có thể triển khai interface. Bên trong một phương thức, $this là case hiện tại, nên match ($this) là cách tự nhiên để gắn dữ liệu cho từng case. Thứ duy nhất enum không thể có là thuộc tính: dữ liệu theo từng case đến từ các phương thức.

<?php
interface HasColor
{
    public function color(): string;
}

enum OrderState: string implements HasColor
{
    case New = 'new';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    const DEFAULT = self::New;

    public function color(): string
    {
        return match ($this) {
            self::New => 'blue',
            self::Shipped => 'orange',
            self::Delivered => 'green',
            self::Cancelled => 'grey',
        };
    }

    public function isFinal(): bool
    {
        return in_array($this, [self::Delivered, self::Cancelled], true);
    }

    public static function open(): array
    {
        return array_filter(self::cases(), fn (self $s) => !$s->isFinal());
    }
}

$state = OrderState::DEFAULT;
echo "{$state->name} is {$state->color()}\n";
var_dump(OrderState::Delivered->isFinal());
echo implode(', ', array_map(fn ($s) => $s->name, OrderState::open())), "\n";
var_dump($state instanceof HasColor);

Enum trong match

match so sánh bằng ===, và một case enum chỉ đồng nhất với chính nó, nên match và enum rất hợp nhau. Nếu bạn quên một case và case đó đi đến match, PHP ném ra UnhandledMatchError thay vì lặng lẽ không trả về gì:

<?php
enum Weekday: int
{
    case Mon = 1;
    case Tue = 2;
    case Wed = 3;
    case Thu = 4;
    case Fri = 5;
    case Sat = 6;
    case Sun = 7;
}

function kind(Weekday $d): string
{
    return match ($d) {
        Weekday::Sat, Weekday::Sun => 'weekend',
        default => 'workday',
    };
}

foreach ([Weekday::Fri, Weekday::Sat, Weekday::from(1)] as $day) {
    echo $day->name, ': ', kind($day), "\n";
}

$tomorrow = Weekday::tryFrom(Weekday::Sun->value + 1) ?? Weekday::Mon;
echo 'After Sun comes ', $tomorrow->name, "\n";

Xem match để biết match khác switch như thế nào.

Enum trong JSON và dưới dạng chuỗi

json_encode() ghi một case của backed enum thành giá trị của nó. Pure enum thì không encode được, và echo bất kỳ case nào cũng thất bại, vì enum là một đối tượng, không phải chuỗi. Hãy in ->value hoặc ->name:

<?php
enum Role: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}

$user = ['name' => 'Ada', 'role' => Role::Admin];
echo json_encode($user), "\n";

$data = json_decode('{"name":"Linus","role":"editor"}', true);
$role = Role::from($data['role']);
var_dump($role);

echo 'Role: ' . $role->value . "\n";
echo 'Name: ' . $role->name . "\n";

echo Role::Admin; ném ra Error ("Object of class Role could not be converted to string"), và enum không thể triển khai __toString(). Khi đọc vào, JSON chỉ cho bạn một chuỗi thường, nên hãy chuyển nó bằng from() hoặc tryFrom() như trên. Xem thêm về encode ở json_encode.

Lỗi thường gặp với enum

Có ba lỗi lặp đi lặp lại. Một case không bao giờ bằng giá trị của nó, một case không thể làm khóa mảng, và new không dùng được với enum:

<?php
enum Status: string
{
    case Active = 'active';
    case Banned = 'banned';
}

// 1. A case is an object, not its value
var_dump(Status::Active == 'active');          // false
var_dump(Status::Active->value === 'active');  // true

// 2. Use ->value as an array key
$counts = [];
foreach ([Status::Active, Status::Banned, Status::Active] as $s) {
    $counts[$s->value] = ($counts[$s->value] ?? 0) + 1;
}
print_r($counts);

try {
    $bad = [Status::Active => 1];
} catch (TypeError $e) {
    echo 'Array key: ', $e->getMessage(), "\n";
}

// 3. Cases are created by PHP, never with new
try {
    $s = new Status();
} catch (Error $e) {
    echo $e->getMessage(), "\n";
}

Nếu bạn cần một bảng ánh xạ dùng chính các case làm khóa, hãy dùng SplObjectStorage hoặc WeakMap, vốn nhận đối tượng làm khóa.