デフォルトでは、列挙型はスカラー値の情報を持っていません。 単なるシングルトンオブジェクトです。 しかし、列挙型の case をデータベースや、 類似のデータストアで読み書きする必要があるケースが多くあります。 よって、ビルトインの (シリアライズ可能であることが自明な) スカラー値を持つ case があると、本質的に役に立ちます。
列挙型にスカラー値を定義するには、以下のようにします:
<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
?>スカラー値を持つ case を、"Backed Case" と呼びます。 なぜなら、オブジェクトよりもシンプルな値に依存して(Backed)いるからです。 全ての case が Backed Case である列挙型を "Backed Enum" と呼びます。 Backed Enum には Backed Case のみを含めることができます。 Pure Enum には Pure Case だけを含めることができます。
Backed Enum は、整数、または文字列の値を持つことができます。
そして、単一の列挙型が一度に持つことの出来る型はひとつだけです
(つまり、int|string のような union
型はサポートしていないということです)。
列挙型がスカラー情報を持つとマークすると、
全ての case はユニークなスカラーの値を明示的に定義しなければいけません。
自動生成されるスカラー値 (例: 整数の連番) は存在しません。
Backed Enum の case の値は、全てユニークでなければいけません。
つまり、ふたつの Backed Enum の case は、
同じスカラー値を持ってはいけないということです。
しかし、定数は case を参照していても構わないので、
別名を作成することはできます。
列挙型と定数
も参照ください。
スカラー値は、定数のスカラー式でなければいけません。
PHP 8.2.0 より前のバージョンでは、
スカラー値はリテラルか、リテラルを表す式でなければいけませんでした。
これは、定数や定数式はサポートされていなかったことを意味します。
つまり、1 + 1 は許されますが、
1 + SOME_CONST は許されていませんでした。
Backed Enum の case は、追加の読み取り専用のプロパティ
value を持っています。
これは、Backed Enum の定義で指定された値です。
<?php
print Suit::Clubs->value;
// "C" と表示
?>
value プロパティを強制的に読み取り専用にするため、
そのリファレンスを変数には代入できません。
つまり、以下のようなコードはエラーになります:
<?php
$suit = Suit::Clubs;
$ref = &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>Backed Enum は内部的に BackedEnum インターフェイスを実装しています。 このメソッドは、以下の2つのメソッドを公開しています:
from(int|string): self
スカラー値を受け取り、対応する Enum の case を返します。
対応する case がない場合は、
ValueError
がスローされます。
このメソッドは、入力のスカラー値が信頼でき、
存在しない enum
の値はアプリケーションを停止すべきエラーとみなせる場合に役立ちます。
tryFrom(int|string): ?self
スカラー値を受け取り、対応する Enum の case を返します。
対応する case がない場合は、null を返します。
このメソッドは、入力のスカラー値が信頼できない場合で、
呼び出し側が独自のエラーハンドリングや、
デフォルト値のロジックを実装したい場合に役立ちます。
from() と tryFrom()
メソッドは、標準の 弱い/強い 型付けのルールに従います。
弱い型付けのルールでは、整数または文字列を受け入れ、
システムは値をそれに従って自動変換します。
厳密な型付けモードの場合、文字列型の Backed Enum に整数値を渡す
(またはその逆をする) と、TypeError が発生します。
float についても、全ての場合に同じ型付けのルールに従います。
それ以外の型については、どちらのモードでも TypeError が発生します。
<?php
$record = get_stuff_from_database($id);
print $record['suit'];
$suit = Suit::from($record['suit']);
// 不正なデータを渡すと、次のようなエラーが発生 -> ValueError: "X" is not a valid scalar value for enum "Suit"
print $suit->value;
$suit = Suit::tryFrom('A') ?? Suit::Spades;
// 不正なデータに対しては null を返すので、Suit::Spades が代わりに使われます。
print $suit->value;
?>
Backed Enum において、手動で from() や
tryFrom() メソッドを定義すると、
致命的なエラーが発生します。