PHP Conference Japan 2024

支援型列舉

預設情況下,列舉成員沒有純量對應值。它們只是單例物件。然而,在很多情況下,列舉成員需要能夠往返於資料庫或類似的資料儲存區,因此內建一個純量(因此易於序列化)對應值是很有用的。

要為列舉定義純量對應值,語法如下:

<?php

enum Suit: string
{
case
Hearts = 'H';
case
Diamonds = 'D';
case
Clubs = 'C';
case
Spades = 'S';
}
?>

具有純量等價值的成員稱為「支援型成員 (Backed Case)」,因為它是由一個更簡單的值「支援」。一個包含所有支援型成員的列舉稱為「支援型列舉 (Backed Enum)」。支援型列舉只能包含支援型成員。「純列舉 (Pure Enum)」只能包含「純成員 (Pure Case)」。

支援型列舉可以由 `int` 或 `string` 類型支援,且一個給定的列舉一次僅支援單一類型(也就是說,不支援 `int|string` 的聯集)。如果一個列舉被標記為具有純量等價值,則所有成員都必須明確定義一個唯一的純量等價值。沒有自動生成的純量等價值(例如,連續的整數)。支援型成員的值必須是唯一的;兩個支援型列舉成員不能具有相同的純量等價值。然而,一個常數可以參考一個成員,有效地建立一個別名。詳見列舉常數

等價值必須是字面值或字面值表達式。不支援常數和常數表達式。也就是說,允許 `1 + 1`,但不允許 `1 + SOME_CONST`。

支援型成員有一個額外的唯讀屬性 `value`,它是在定義中指定的值。

<?php

print Suit::Clubs->value;
// 顯示 "C"
?>

為了強制 `value` 屬性為唯讀,變數不能被賦值為它的參考。也就是說,以下程式碼會拋出錯誤:

<?php

$suit
= Suit::Clubs;
$ref = &$suit->value;
// 錯誤:無法取得 Suit::$value 屬性的參考
?>

支援型列舉實作了一個內部 BackedEnum 介介面,它公開了兩個額外的方法:

  • `from(int|string): self` 會接受一個純量並返回對應的列舉成員。如果找不到,它會拋出 ValueError。這主要用於輸入純量是可信的,且缺少列舉值應被視為應用程式停止錯誤的情況。
  • tryFrom(int|string): ?self 會接受一個純量值並回傳對應的列舉成員。如果找不到對應的成員,則會回傳 null。這在輸入純量值不可信,且呼叫者想要自行處理錯誤或設定預設值的情況下特別有用。

from()tryFrom() 方法遵循標準的弱/強型別規則。在弱型別模式中,傳遞整數或字串皆可接受,系統會相應地強制轉換值。傳遞浮點數也可以運作並被強制轉換。在嚴格型別模式中,將整數傳遞給以字串為基礎的列舉的 from() 方法(反之亦然)將導致 TypeError,在任何情況下傳遞浮點數也會導致同樣的錯誤。所有其他參數型別在兩種模式下都會拋出 TypeError。

<?php

$record
= get_stuff_from_database($id);
print
$record['suit'];

$suit = Suit::from($record['suit']);
// 無效的資料會拋出 ValueError:「X」不是列舉「Suit」的有效純量值
print $suit->value;

$suit = Suit::tryFrom('A') ?? Suit::Spades;
// 無效的資料會回傳 null,因此會使用 Suit::Spades
print $suit->value;
?>

在支援型列舉中手動定義 from()tryFrom() 方法將導致嚴重錯誤。

新增註解

使用者貢獻的註解

此頁面沒有使用者貢獻的註解。
To Top