【PHP8.x】enum_exists関数の使い方

<?php

/**
 * トランプのスーツを表すBacked Enum
 *
 * PHP 8.1以降で利用可能な列挙型(enum)の例です。
 */
enum Suit: string
{
    case Hearts = 'H';
    case Diamonds = 'D';
    case Clubs = 'C';
    case Spades = 'S';
}

/**
 * 指定されたenumとそのケース(値)が存在するかを確認し、結果を表示します。
 *
 * @param string $enumClassName チェックしたいenumのクラス名
 * @param string $caseName チェックしたいケース名
 * @return void
 */
function checkEnumAndCase(string $enumClassName, string $caseName): void
{
    // enum_exists() を使用して、指定された名前のenumが定義されているかを確認します。
    if (enum_exists($enumClassName)) {
        echo "OK: enum '{$enumClassName}' は存在します。" . PHP_EOL;

        // enumが存在する場合、次にそのenumに特定のケース(値)が存在するかを確認します。
        // enumのケースは内部的にクラス定数として扱われるため、defined()でチェックできます。
        $constantName = $enumClassName . '::' . $caseName;
        if (defined($constantName)) {
            echo "OK: ケース '{$caseName}' は '{$enumClassName}' に存在します。" . PHP_EOL;
        } else {
            echo "NG: ケース '{$caseName}' は '{$enumClassName}' に存在しません。" . PHP_EOL;
        }
    } else {
        echo "NG: enum '{$enumClassName}' は存在しません。" . PHP_EOL;
    }
    echo "----------------------------------------" . PHP_EOL;
}


// --- 実行例 ---

// 存在するenumと存在するケースをチェック
checkEnumAndCase(Suit::class, 'Hearts');

// 存在するenumと存在しないケースをチェック
checkEnumAndCase(Suit::class, 'Joker');

// 存在しないenumをチェック
checkEnumAndCase('Color', 'Red');

?>

PHPのenum_exists関数は、指定された名前のEnum（列挙型）が現在の環境に存在するかどうかを確認するために使用されます。この関数は、PHP 8.1以降で導入されたEnumが利用可能か、または特定のEnumが定義されているかを実行時にチェックする際に役立ちます。

引数には、確認したいEnumの完全修飾クラス名を文字列で渡します。例えば、サンプルコードのSuit::classのように指定します。オプションの第二引数$autoloadはデフォルトでtrueであり、指定されたEnumが見つからない場合にPHPのオートロード機構を試みるかどうかを制御します。戻り値は真偽値（bool）で、Enumが存在すればtrue、存在しなければfalseを返します。

サンプルコードでは、トランプのスーツを表すSuitというEnumが定義されています。checkEnumAndCase関数では、まずenum_existsを用いてSuitのようなEnumクラス自体がPHPに登録されているかを確認します。Enumが存在すると確認できた後、そのEnumに特定のケース（例えばHeartsやJoker）が存在するかどうかは、enum_existsでは直接判断できません。Enumのケースは内部的にはクラス定数として扱われるため、defined()関数に「Enum名::ケース名」という形式の文字列を渡すことで存在をチェックしています。

実行例を通じて、存在するEnumと存在するケース、存在するEnumと存在しないケース、そして存在しないEnumをそれぞれチェックし、enum_existsとdefinedを組み合わせることで、Enumとその中の特定のケースの両方を確実に存在確認できる方法が示されています。

<?php

/**
 * enum_exists 関数の使用例
 */

// Enum が存在するか確認する
if (enum_exists(MyEnum::class)) {
    echo "Enum MyEnum が存在します。\n";
} else {
    echo "Enum MyEnum が存在しません。\n";
}

// 存在しない Enum を確認する
if (!enum_exists("NonExistentEnum")) {
    echo "Enum NonExistentEnum は存在しません。\n";
} else {
    echo "Enum NonExistentEnum が存在します。\n";
}

// Enum の定義 (上記の例を動作させるために必要)
enum MyEnum {
    case VALUE1;
    case VALUE2;
}

?>

enum_exists関数は、指定されたEnum型が定義されているかどうかを確認するために使用されます。PHP 8.1で導入されたEnum型は、特定の値を事前に定義し、それ以外の値を受け付けないようにする機能です。この関数を利用することで、プログラム実行時にEnum型が存在するかどうかを動的に判断できます。

enum_exists関数は、第一引数にEnum型の名前を文字列で指定します。この名前空間を含んだ完全修飾名である必要があります（例: MyNamespace\MyEnum::class）。第二引数には、autoloadというオプションの引数があり、デフォルト値はtrueです。autoloadがtrueの場合、Enum型が見つからなければ、自動的にクラスのオートローダーが呼び出され、Enum型の定義が試みられます。autoloadがfalseの場合、オートローダーは呼び出されません。

戻り値はbool型で、Enum型が存在する場合はtrue、存在しない場合はfalseを返します。サンプルコードでは、まずMyEnumというEnum型が存在するかどうかを確認しています。存在する場合は「Enum MyEnum が存在します。」というメッセージが表示されます。次に、存在しないEnum型であるNonExistentEnumの存在を確認し、存在しないことを確認しています。enum MyEnumの定義は、enum_exists関数の使用例を動作させるために必須です。この関数を使用することで、Enum型を利用する前にその存在を確認し、エラーを未然に防ぐことができます。

<?php

/**
 * ユーザーの状態を表すEnum。
 *
 * PHP 8.1以降で導入されたEnumは、関連する定数をグループ化し、
 * 型安全性を提供します。
 */
enum UserStatus
{
    case Active;
    case Inactive;
    case Pending;
}

/**
 * アプリケーション設定を表すEnum。
 * バックドEnumとして文字列値を持ちます。
 */
enum AppConfig: string
{
    case DebugMode = 'debug';
    case ProductionMode = 'production';
}

/**
 * `enum_exists` 関数の基本的な使用例を示します。
 *
 * `enum_exists(string $enum, bool $autoload = true)` は、
 * 指定された名前のEnum型が定義されているかどうかを真偽値で返します。
 *
 * @return void
 */
function demonstrateEnumExists(): void
{
    echo "--- `enum_exists` 関数によるEnum型の存在チェック ---" . PHP_EOL;

    // 1. 存在するEnum型名を指定してチェック
    // 'UserStatus' というEnumが定義されているため、trueを返します。
    $userStatusExists = enum_exists('UserStatus');
    echo "Enum 'UserStatus' は存在しますか？: " . ($userStatusExists ? 'はい' : 'いいえ') . PHP_EOL; // 期待される出力: はい

    // 'AppConfig' というEnumも定義されているため、trueを返します。
    $appConfigExists = enum_exists('AppConfig');
    echo "Enum 'AppConfig' は存在しますか？: " . ($appConfigExists ? 'はい' : 'いいえ') . PHP_EOL; // 期待される出力: はい

    // 2. 存在しないEnum型名を指定してチェック
    // 'NonExistentEnum' は定義されていないため、falseを返します。
    $nonExistentEnumExists = enum_exists('NonExistentEnum');
    echo "Enum 'NonExistentEnum' は存在しますか？: " . ($nonExistentEnumExists ? 'はい' : 'いいえ') . PHP_EOL; // 期待される出力: いいえ

    echo PHP_EOL;
    echo "--- autoload 引数について ---" . PHP_EOL;
    echo "`enum_exists`関数の第二引数`$autoload`はデフォルトで`true`です。" . PHP_EOL;
    echo "これにより、指定されたEnumがまだロードされていない場合でも、PHPは自動的に対応するファイルを検索し、" . PHP_EOL;
    echo "そのEnumをロードしようと試みます。通常はこのデフォルト設定で問題ありません。" . PHP_EOL;
}

// 上記の関数を実行して、結果を出力します。
demonstrateEnumExists();

PHPのenum_exists関数は、指定された名前のEnum（列挙型）がアプリケーション内に定義されているかどうかを確認するために使用される関数です。この関数は、PHP 8.1以降で導入されたEnum型の存在チェックに利用できます。

第一引数$enumには、存在を確認したいEnum型の完全な名前を文字列で指定します。例えば、サンプルコードで定義されているUserStatusやAppConfigといったEnumの名前を指定します。

第二引数$autoloadはオプションで、デフォルトはtrueに設定されています。この引数がtrueの場合、指定されたEnumがまだPHPによってロードされていない場合でも、PHPはオートロード機能を使ってそのEnumを定義しているファイルを自動的に検索し、ロードを試みます。特別な理由がない限り、通常はこのデフォルト設定のままで問題ありません。

enum_exists関数の戻り値はbool型です。指定された名前のEnum型が定義されていればtrueを、存在しなければfalseを返します。

サンプルコードでは、まずUserStatusとAppConfigという二つのEnumを定義しています。enum_exists('UserStatus')やenum_exists('AppConfig')の呼び出しは、これらのEnumが定義されているためtrue（「はい」）を返します。これに対し、定義されていないNonExistentEnumを指定したenum_exists('NonExistentEnum')の呼び出しは、false（「いいえ」）を返します。このように、この関数を使うことで、プログラムの実行中に特定のEnumが利用可能かどうかを動的に、かつ安全に確認できます。