التعدادات في PHP: enum المدعوم وfrom() وtryFrom() وcases()

يعرّف التعداد في PHP (PHP 8.1 وما بعدها) نوعًا بمجموعة ثابتة من القيم الممكنة، هي حالاته: enum Status { case Active; case Banned; }. تستخدم الحالة على شكل Status::Active، والمعامل ذو النوع Status لا يقبل شيئًا آخر. ويعطي التعداد المدعوم، 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";

قبل التعدادات، كان الشيء نفسه قائمة من الثوابت النصية، ولم يكن هناك ما يمنع خطأً إملائيًا مثل 'actve' من الوصول إلى قاعدة البيانات. ومع Status نوعًا للمعامل، لا يمكن تمرير إلا الحالات الثلاث.

التعدادات الخالصة والتعدادات المدعومة

حالات التعداد الخالص أسماء فقط. ويصرّح التعداد المدعوم بنوع بعد الاسم، int أو string، ويجب عندها أن تكون لكل حالة قيمة فريدة من ذلك النوع. لكل حالة ->name؛ ولا تملك ->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);

اختر تعدادًا مدعومًا كلما غادرت القيمة البرنامج: عمود قاعدة بيانات، أو رابط، أو حقل نموذج، أو JSON. واختر تعدادًا خالصًا للقيم التي لا توجد إلا داخل الشيفرة، مثل حالة محلل نحوي.

تحويل قيمة بـ from() وtryFrom()

تحصل التعدادات المدعومة على تابعين ساكنين لتحويل قيمة مخزنة مرة أخرى إلى حالة. ترمي 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، تعيد Priority::from('5') الحالة Priority::Normal في الوضع الافتراضي لأن '5' تُحوَّل إلى 5 أولًا، وPriority::from('5x') خطأ TypeError، ومع declare(strict_types=1) يكون أي نص خطأ TypeError. ويشمل ذلك tryFrom(): ترمي Priority::tryFrom('abc') خطأً بدل إعادة null، لذا افحص مُدخلات النموذج لتعداد 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، فلا يُحدَّد أي خيار.

توابع التعداد وثوابته وواجهاته

يمكن أن تكون للتعدادات توابع وتوابع ساكنة وثوابت، ويمكنها تنفيذ واجهات. داخل التابع، $this هي الحالة الحالية، وهذا يجعل match ($this) الطريقة الطبيعية لربط بيانات بكل حالة. وما لا يمكن أن يكون للتعداد هو الخصائص: البيانات الخاصة بكل حالة تأتي من التوابع.

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

تقارن match بـ ===، والحالة في التعداد مطابقة لنفسها فقط، لذا يتلاءم match والتعدادات. إذا نسيت حالة ووصلت تلك الحالة إلى 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.

التعدادات في JSON وبوصفها نصوصًا

تكتب json_encode() الحالة المدعومة على شكل قيمتها. ولا يمكن ترميز التعداد الخالص، وتفشل 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")، ولا يمكن للتعدادات تنفيذ __toString(). وعند العودة، يعطي JSON نصًا عاديًا، فحوّله بـ from() أو tryFrom() كما هو معروض. مزيد عن الترميز في json_encode.

أخطاء شائعة مع التعدادات

تتكرر ثلاثة أخطاء كثيرًا. الحالة لا تساوي قيمتها أبدًا، ولا يمكن أن تكون الحالة مفتاح مصفوفة، ولا تعمل 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";
}

إذا احتجت إلى خريطة مفاتيحها الحالات نفسها، فاستخدم SplObjectStorage أو WeakMap، اللتين تقبلان الكائنات مفاتيح.