enum ב-PHP: backed enums, from(), tryFrom() ו-cases()

enum ב-PHP (PHP 8.1 ומעלה) מגדיר טיפוס עם קבוצה קבועה של ערכים אפשריים, המקרים שלו: enum Status { case Active; case Banned; }. משתמשים במקרה כ-Status::Active, ופרמטר עם הטיפוס Status לא מקבל שום דבר אחר. backed enum, enum Status: string, נותן גם לכל מקרה ערך שאפשר לשמור ולהמיר בחזרה עם 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";

לפני enums, אותו דבר היה רשימה של קבועי מחרוזת, ושום דבר לא מנע משגיאת הקלדה כמו 'actve' להגיע למסד הנתונים. עם Status כטיפוס הפרמטר, אפשר להעביר רק את שלושת המקרים.

enums טהורים ו-backed enums

ב-enum טהור המקרים הם רק שמות. backed enum מצהיר על טיפוס אחרי השם, int או string, ולכל מקרה חייב אז להיות ערך ייחודי מהטיפוס הזה. לכל מקרה יש ->name; רק למקרים של backed יש ->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 טהור לערכים שקיימים רק בתוך הקוד, כמו המצב של parser.

המרת ערך עם from() ו-tryFrom()

backed enums מקבלים שתי מתודות סטטיות להפיכת ערך שמור בחזרה למקרה. 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() על ערכים שהקוד שלכם כתב, שבהם ערך לא מוכר אומר באג שאתם רוצים לשמוע עליו. הארגומנט עוקב אחרי כללי טיפוס הפרמטר הרגילים: ב-enum של int, Priority::from('5') מחזירה Priority::Normal במצב ברירת המחדל כי '5' מומר קודם ל-5, Priority::from('5x') היא TypeError, ותחת declare(strict_types=1) כל מחרוזת היא TypeError. זה כולל את tryFrom(): Priority::tryFrom('abc') זורקת במקום להחזיר null, אז בדקו קלט מטופס ל-enum של int קודם עם filter_var($raw, FILTER_VALIDATE_INT).

רשימת כל המקרים עם cases()

Enum::cases() מחזירה מערך של כל מקרה, לפי סדר ההצהרה. כך בונים רשימה נפתחת, מאמתים רשימה או מקבלים את כל הערכים עם 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. ערך מזויף כמו plan=gold נותן null, ואף אפשרות לא נבחרת.

מתודות, קבועים וממשקים ב-enum

ל-enums יכולות להיות מתודות, מתודות סטטיות וקבועים, והם יכולים לממש ממשקים. בתוך מתודה, $this הוא המקרה הנוכחי, ולכן match ($this) היא הדרך הטבעית לחבר נתונים לכל מקרה. מה שאין ל-enum זה מאפיינים: נתונים לכל מקרה מגיעים ממתודות.

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

enums בתוך match

match משווה עם ===, ומקרה של enum זהה רק לעצמו, ולכן match ו-enums מתאימים זה לזה. אם שוכחים מקרה והמקרה הזה מגיע ל-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 על ההבדלים בין match ל-switch.

enums ב-JSON וכמחרוזות

json_encode() כותבת מקרה של backed enum כערך שלו. enum טהור אי אפשר לקודד, ו-echo של כל מקרה נכשל, כי enum הוא אובייקט, לא מחרוזת. הדפיסו במקום זאת את ->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"), ו-enums לא יכולים לממש __toString(). בדרך חזרה, JSON נותן מחרוזת פשוטה, אז המירו אותה עם from() או tryFrom() כמו שמוצג. עוד על קידוד ב-json_encode.

טעויות נפוצות ב-enums

שלוש שגיאות חוזרות שוב ושוב. מקרה אף פעם לא שווה לערך שלו, מקרה לא יכול להיות מפתח מערך, ו-new לא עובד על 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";
}

אם אתם צריכים מפה שהמפתחות שלה הם המקרים עצמם, השתמשו ב-SplObjectStorage או ב-WeakMap, שמקבלים אובייקטים כמפתחות.