【PHP8.x】ReflectionEnumBackedCase::getDocComment()メソッドの使い方

Copy
1<?php
2
3/**
4 * ユーザーのステータスを表すバック付きEnum。
5 * このEnumはPHP 8.1以降で利用可能です。
6 */
7enum UserStatus: string
8{
9    /**
10     * アクティブなユーザー状態を示します。
11     * このケースのPHPDocコメントはReflection APIで取得できます。
12     */
13    case ACTIVE = 'active';
14
15    /**
16     * 非アクティブなユーザー状態を示します。
17     */
18    case INACTIVE = 'inactive';
19
20    case PENDING = 'pending'; // このケースにはPHPDocコメントがありません
21}
22
23// Reflection APIを使用してEnumケースのドキュメントコメントを取得する例
24
25try {
26    // UserStatus EnumのReflectionオブジェクトを作成します。
27    // これにより、Enum全体の情報にアクセスできるようになります。
28    $reflectionEnum = new ReflectionEnum(UserStatus::class);
29
30    // 'ACTIVE' という名前のEnumケースのReflectionEnumBackedCaseオブジェクトを取得します。
31    // Backed Enum（バック付きEnum）のケースはReflectionEnumBackedCaseクラスで表現されます。
32    $reflectionCase = $reflectionEnum->getCase('ACTIVE');
33
34    // ReflectionEnumBackedCaseオブジェクトのgetDocCommentメソッドを呼び出して、
35    // Enumケースに記述されたPHPDocコメントを取得します。
36    // コメントがない場合は false を返します。
37    $docCommentForActive = $reflectionCase->getDocComment();
38
39    if ($docCommentForActive !== false) {
40        echo "ケース 'ACTIVE' のPHPDocコメント:\n";
41        echo $docCommentForActive . "\n\n";
42    } else {
43        echo "ケース 'ACTIVE' にはPHPDocコメントがありません。\n\n";
44    }
45
46    // PHPDocコメントがないケースの例を見てみましょう ('PENDING')
47    $reflectionCaseForPending = $reflectionEnum->getCase('PENDING');
48    $docCommentForPending = $reflectionCaseForPending->getDocComment();
49
50    if ($docCommentForPending !== false) {
51        echo "ケース 'PENDING' のPHPDocコメント:\n";
52        echo $docCommentForPending . "\n";
53    } else {
54        echo "ケース 'PENDING' にはPHPDocコメントがありません。\n";
55    }
56
57} catch (ReflectionException $e) {
58    // Enumクラスが見つからない場合などに発生するエラーを処理します。
59    echo "エラー: " . $e->getMessage() . "\n";
60}
61
62?>

PHPのReflectionEnumBackedCase::getDocCommentメソッドは、Enum（列挙型）の特定のケースに記述されたPHPDocコメントを取得するために使用されます。PHPDocコメントとは、コードの説明やドキュメント生成に利用される特殊なコメント形式のことです。

このメソッドを利用するには、まず対象のEnumクラス名を指定してReflectionEnumオブジェクトを作成します。次に、そのReflectionEnumオブジェクトのgetCaseメソッドを使って、取得したい特定のEnumケース（例: ACTIVE）に対応するReflectionEnumBackedCaseオブジェクトを取得します。このReflectionEnumBackedCaseオブジェクトに対してgetDocCommentメソッドを呼び出すことで、そのEnumケースに書かれたPHPDocコメントを取得できます。

getDocCommentメソッドは引数を取りません。戻り値は、該当するEnumケースにPHPDocコメントが存在すればそのコメント内容が文字列（string）として返されます。もしPHPDocコメントが記述されていない場合は、falseが戻り値として返されます。サンプルコードのUserStatus Enumでは、ACTIVEケースにコメントがあるため文字列が取得され、PENDINGケースにはコメントがないためfalseが返される挙動を確認できます。この機能は、Enumの定義をプログラム的に分析し、ドキュメントを自動生成する際などに役立ちます。

Copy
1<?php
2
3/**
4 * PHP 8.1 以降で導入されたBacked Enum（バックアップ型列挙型）の例です。
5 * ReflectionEnumBackedCase クラスと getDocComment メソッドはPHP 8.1以降で利用可能です。
6 *
7 * Backed Enum は、各ケースにスカラー値（文字列または整数）を関連付けることができる列挙型です。
8 */
9enum TaskStatus: string
10{
11    /**
12     * タスクが保留中であり、処理を待っている状態を示します。
13     * このコメントは複数行にわたるPHPDocコメントの例です。
14     *
15     * @var string 内部的には 'pending' という文字列値で表現されます。
16     */
17    case PENDING = 'pending';
18
19    /**
20     * タスクが完了し、正常に処理された状態を示します。
21     *
22     * @var string 内部的には 'completed' という文字列値で表現されます。
23     */
24    case COMPLETED = 'completed';
25
26    // このケースには明示的なPHPDocコメントがありません。
27    case FAILED = 'failed';
28}
29
30/**
31 * 指定されたBacked Enumの各ケースからPHPDocコメントを取得し、表示する関数です。
32 * この機能は、PHPDocジェネレータ（ドキュメント生成ツール）がソースコードを解析し、
33 * 各要素のドキュメントを抽出する際に行う基本的なステップを示します。
34 *
35 * @param class-string<\UnitEnum> $enumClassName リフレクションを行うBacked Enumの完全修飾クラス名。
36 * @return void
37 */
38function inspectBackedEnumDocComments(string $enumClassName): void
39{
40    echo "--- Backed Enum '{$enumClassName}' のPHPDocコメントを検査中 ---\n\n";
41
42    try {
43        // ReflectionEnum を使用して、Enum自体をリフレクションします。
44        // ReflectionEnumBackedCase は ReflectionEnumCase の子クラスです。
45        $reflectionEnum = new ReflectionEnum($enumClassName);
46
47        // Enumの定義されている全てのケースを取得します。
48        foreach ($reflectionEnum->getCases() as $case) {
49            // getDocComment メソッドは ReflectionEnumBackedCase クラスのものです。
50            // そのため、Backed Enumのケースであることを確認する必要があります。
51            // (PHP 8.1以降では、Backed Enumのケースは自動的にReflectionEnumBackedCaseのインスタンスになります)
52            if ($case instanceof ReflectionEnumBackedCase) {
53                echo "ケース名: " . $case->getName() . "\n";
54                echo "ケース値: " . $case->getValue() . "\n";
55
56                // getDocComment メソッドを呼び出して、このケースに関連付けられたPHPDocコメントを取得します。
57                // コメントが存在しない場合は false が返されます。
58                $docComment = $case->getDocComment();
59
60                if ($docComment !== false) {
61                    echo "取得されたPHPDocコメント:\n";
62                    echo "----------------------------------------\n";
63                    echo $docComment . "\n";
64                    echo "----------------------------------------\n\n";
65                } else {
66                    echo "PHPDocコメント: (このケースにはコメントが見つかりませんでした)\n\n";
67                }
68            } else {
69                // Pure Enum (Unit Enum) のケースの場合、またはPHP 8.1未満の環境の場合
70                // このサンプルはReflectionEnumBackedCase::getDocCommentに特化しているため、
71                // Backed Enumではないケースは処理しません。
72                echo "ケース名: " . $case->getName() . " (Backed Enumのケースではないか、PHP 8.1未満です)\n";
73                echo "注意: getDocComment() は ReflectionEnumBackedCase に固有のメソッドです。\n\n";
74            }
75        }
76    } catch (ReflectionException $e) {
77        // Enumクラスが見つからない、またはリフレクションに失敗した場合のエラーハンドリング
78        echo "エラー: Enum '{$enumClassName}' のリフレクションに失敗しました。" . $e->getMessage() . "\n";
79        echo "PHP 8.1以降の環境で、かつ'{$enumClassName}'が有効なBacked Enumであることを確認してください。\n";
80    }
81}
82
83// 上で定義した Backed Enum (TaskStatus) に対して関数を実行します。
84inspectBackedEnumDocComments(TaskStatus::class);

ReflectionEnumBackedCase::getDocCommentメソッドは、PHP 8.1以降で導入されたBacked Enum（バックアップ型列挙型）の特定のケースに付与されたPHPDocコメントを取得するための機能です。Backed Enumは、各ケースに文字列や数値などのスカラー値を関連付けられる列挙型で、そのケースの目的や詳細を説明するためにPHPDocコメント（/** ... */で囲まれたドキュメント）を記述できます。

このメソッドは引数を取らずに呼び出します。もし対象のケースにPHPDocコメントが存在すれば、そのコメント内容を文字列として返します。コメントが一切存在しない場合はfalseを返します。これにより、プログラムはEnumの定義から、その各要素に関する説明情報を動的に取得することが可能です。

本サンプルコードでは、TaskStatusというBacked Enumを定義し、その各ケースに付与されたPHPDocコメントをReflectionEnumおよびReflectionEnumBackedCaseクラスを利用して抽出、表示しています。特にPENDINGやCOMPLETEDケースにはコメントが記述されており、FAILEDケースにはコメントがないため、getDocCommentメソッドがコメントの有無に応じて異なる値を返す挙動を確認できます。この機能は、ソースコードから自動的にドキュメントを生成するPHPDocジェネレータ（ドキュメント生成ツール）が、Enumの各要素の説明文を読み取る際に行う基本的な処理の一つです。