التعدادات (PHP 8.1)

جزء من قسم البرمجة كائنية التوجه في رحلة PHP على Coddy. الدرس 59 من 91.

قبل PHP 8.1، كان تمثيل مجموعة ثابتة من القيم مثل الحالات أو الأنواع يعني استخدام ثوابت class أو سلاسل نصية سحرية - وهما نهجان عرضة للأخطاء. توفر التعدادات (enumerations) طريقة مناسبة لتعريف نوع لا يمكنه احتواء سوى قيم محددة ومُعرَّفة مسبقًا.

عرّف تعدادًا باستخدام الكلمة المفتاحية enum:

<?php
enum Status {
    case Pending;
    case Active;
    case Completed;
}

$status = Status::Active;
echo $status->name;

الناتج:

Active

يمكن أن تحتوي التعدادات أيضًا على قيم backed - وهي قيم نصية أو صحيحة مرتبطة بكل حالة. وهذا مفيد عند تخزين التعدادات في قواعد البيانات أو واجهات API:

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

$status = Status::Active;
echo $status->value;

الناتج:

active

توفر تعدادات Backed طريقة from() لإنشاء تعداد من قيمته، وطريقة tryFrom() التي تُرجع null بدلًا من طرح خطأ للقيم invalid:

<?php
$status = Status::from('active');      // يُرجع Status::Active
$invalid = Status::tryFrom('unknown'); // يُرجع null

يمكن أن تحتوي التعدادات أيضًا على أساليب، مما يجعلها قوية لتغليف المنطق ذي الصلة. وهي تعمل بسلاسة مع تلميحات الأنواع، مما يضمن أن دوالك لا تقبل إلا القيم الصالحة — فلا مزيد من التحقق مما إذا كانت سلسلة نصية تطابق الخيارات المتوقعة.

التحدي

سهل

لنَبْنِ نظامًا لإدارة الطلبات يستخدم التعدادات لتمثيل حالات الطلبات بطريقة آمنة من حيث النوع. بدلًا من الاعتماد على سلاسل نصية قد تحتوي على أخطاء إملائية أو تكون غير صالحة، ستنشئ تعدادًا من نوع backed يربط كل حالة بقيمة ملائمة لقاعدة البيانات.

ستنظّم التعليمات البرمجية عبر ثلاثة ملفات:

OrderStatus.php: أنشئ تعدادًا نصيًا من نوع backed يسمى OrderStatus مع four حالات:
- Pending مدعومة بالقيمة 'pending'
- Processing مدعومة بالقيمة 'processing'
- Shipped مدعومة بالقيمة 'shipped'
- Delivered مدعومة بالقيمة 'delivered'
أضف method باسم label() تُرجع وصفًا مقروءًا بشريًا لكل حالة:
- تعيد Pending القيمة "Awaiting confirmation"
- تعيد Processing القيمة "Being prepared"
- تعيد Shipped القيمة "On the way"
- تعيد Delivered القيمة "Order complete"
Order.php: أنشئ class باسم Order يستخدم التعداد. أدرج ملف OrderStatus. يجب أن تقوم الفئة بما يلي:
- تقبل معرّف طلب (من النوع string) وOrderStatus في constructor باستخدام ترقية constructor
- تحتوي على method باسم getInfo() تُرجع "Order [id]: [status label]"
- تحتوي على method باسم getStatusValue() تُرجع القيمة المدعومة للحالة (وهو أمر مفيد لتخزينها في قاعدة البيانات)
main.php: أدرج ملف Order. ستتلقى مُدخلين: معرّف طلب وسلسلة حالة (مثل "shipped"). استخدم tryFrom() لتحويل مُدخل السلسلة بأمان إلى تعداد OrderStatus. إذا كانت الحالة صالحة، أنشئ Order واطبع سطرين:
- نتيجة getInfo()
- نتيجة getStatusValue()
إذا كانت سلسلة الحالة غير صالحة، اطبع "Invalid status".

يوضح هذا التحدي كيف توفر التعدادات أمان الأنواع. لا يمكن لفئة Order قبول سوى الحالات الصالحة، وتتيح لك method tryFrom() التعامل بأمان مع مُدخلات المستخدم دون المخاطرة بقيم غير صالحة.

جرّب بنفسك

<?php

require_once 'Order.php';

// اقرأ المدخلات
$orderId = trim(fgets(STDIN));
$statusString = trim(fgets(STDIN));

// TODO: استخدم OrderStatus::tryFrom() لتحويل سلسلة الحالة بأمان إلى تعداد
// tryFrom() تُرجع null إذا كانت القيمة غير صالحة

// TODO: إذا كانت الحالة صالحة، أنشئ Order واطبع:
// - نتيجة getInfo()
// - نتيجة getStatusValue()

// TODO: If the status is invalid, print "Invalid status"

?>