PHP enum 열거형: backed enum, from(), tryFrom(), cases()

PHP enum(PHP 8.1+)은 가능한 값, 즉 case의 집합이 고정된 타입을 정의합니다: enum Status { case Active; case Banned; }. case는 Status::Active처럼 쓰며, Status 타입의 매개변수는 다른 것을 받지 않습니다. backed enum인 enum Status: string은 각 case에 저장할 수 있는 값도 주며, 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";

enum 이전에는 같은 것을 문자열 상수 목록으로 만들었고, 'actve' 같은 오타가 데이터베이스에 들어가는 것을 막을 방법이 없었습니다. 매개변수 타입이 Status이면 세 case만 넘길 수 있습니다.

순수 enum과 backed enum

순수 enum의 case는 이름뿐입니다. backed enum은 이름 뒤에 int나 string 타입을 선언하며, 그러면 모든 case가 그 타입의 고유한 값을 가져야 합니다. 모든 case에는 ->name이 있고, backed case에만 ->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);

값이 프로그램 밖으로 나간다면 backed enum을 고르세요. 데이터베이스 컬럼, URL, 폼 필드, JSON 등입니다. 파서의 상태처럼 코드 안에만 존재하는 값이라면 순수 enum을 고르세요.

from()과 tryFrom()으로 값 변환하기

backed enum에는 저장된 값을 다시 case로 바꾸는 정적 메서드 두 개가 생깁니다. from()은 알 수 없는 값에 ValueError를 던지고, tryFrom()은 null을 반환하므로 기본값을 위한 ??와 잘 어울립니다.

<?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";
}

사용자가 보낸 것에는 tryFrom()을, 알 수 없는 값이 알고 싶은 버그를 뜻하는 직접 쓴 값에는 from()을 쓰세요. 인수는 일반적인 매개변수 타입 규칙을 따릅니다. int enum에서 기본 모드의 Priority::from('5')는 '5'가 먼저 5로 변환되므로 Priority::Normal을 반환하고, Priority::from('5x')는 TypeError이며, declare(strict_types=1) 아래에서는 어떤 문자열이든 TypeError입니다. tryFrom()도 마찬가지라서 Priority::tryFrom('abc')는 null을 반환하는 대신 예외를 던집니다. 그러니 int enum용 폼 입력은 먼저 filter_var($raw, FILTER_VALIDATE_INT)로 확인하세요.

cases()로 모든 case 나열하기

Enum::cases()는 선언된 순서대로 모든 case의 배열을 반환합니다. 드롭다운을 만들거나, 목록을 검증하거나, 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>';

실행하고 요금제를 고른 뒤 Choose를 누르세요. $_POST['plan']이 채워진 채로 같은 스크립트가 다시 실행되고, tryFrom()이 제출된 문자열을 Plan case로 바꿉니다. plan=gold 같은 위조된 값은 null이 되고 아무 옵션도 선택되지 않습니다.

enum 메서드, 상수, 인터페이스

enum은 메서드, 정적 메서드, 상수를 가질 수 있고 인터페이스를 구현할 수 있습니다. 메서드 안에서 $this는 현재 case이므로 각 case에 데이터를 붙이는 자연스러운 방법은 match ($this)입니다. enum이 가질 수 없는 것은 속성입니다. case별 데이터는 메서드에서 나옵니다.

<?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);

match 속의 enum

match는 ===로 비교하고, enum case는 자기 자신과만 동일하므로 match와 enum은 잘 맞습니다. case를 빠뜨렸는데 그 case가 match에 도달하면 PHP는 조용히 아무것도 반환하지 않는 대신 UnhandledMatchError를 던집니다.

<?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";

match가 switch와 어떻게 다른지는 match를 참고하세요.

JSON과 문자열로서의 enum

json_encode()는 backed case를 그 값으로 씁니다. 순수 enum은 인코딩할 수 없고, enum은 문자열이 아니라 객체이므로 어떤 case든 echo하면 실패합니다. 대신 ->value나 ->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;은 Error("Object of class Role could not be converted to string")를 던지며, enum은 __toString()을 구현할 수 없습니다. 돌아올 때 JSON은 평범한 문자열을 주므로 위처럼 from()이나 tryFrom()으로 변환하세요. 인코딩에 대한 자세한 내용은 json_encode에 있습니다.

흔한 enum 실수

세 가지 에러가 계속 나옵니다. case는 그 값과 절대 같지 않고, case는 배열 키가 될 수 없으며, enum에는 new가 동작하지 않습니다.

<?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";
}

case 자체를 키로 쓰는 맵이 필요하다면 객체를 키로 받는 SplObjectStorage나 WeakMap을 쓰세요.