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

Copy
1<?php
2
3/**
4 * このクラスは、システムのユーザー情報を表します。
5 * プロパティには、PHPDocコメントが記述されています。
6 */
7class UserProfile
8{
9    /**
10     * ユーザーの一意なID。
11     * @var int
12     */
13    public int $id;
14
15    /**
16     * ユーザーの表示名。
17     * @var string
18     */
19    public string $name;
20
21    /**
22     * ユーザーのメールアドレス。
23     * このプロパティにはPHPDocコメントがありません。
24     */
25    public string $emailAddress;
26
27    /**
28     * UserProfileクラスのコンストラクタ。
29     *
30     * @param int $id ユーザーID
31     * @param string $name ユーザー名
32     * @param string $emailAddress メールアドレス
33     */
34    public function __construct(int $id, string $name, string $emailAddress)
35    {
36        $this->id = $id;
37        $this->name = $name;
38        $this->emailAddress = $emailAddress;
39    }
40}
41
42/**
43 * 指定されたクラスの各プロパティからPHPDocコメントを取得し、表示します。
44 * ReflectionProperty::getDocComment() メソッドの基本的な使用例を示します。
45 *
46 * @param string $className PHPDocコメントを調べたいクラスの名前
47 */
48function showPropertyDocComments(string $className): void
49{
50    echo "--- クラス: {$className} のプロパティのDocコメント ---" . PHP_EOL . PHP_EOL;
51
52    try {
53        // ReflectionClassは、クラスの構造に関する情報を取得するためのPHPの機能です。
54        $reflectionClass = new ReflectionClass($className);
55
56        // クラス内のすべてのプロパティ（変数）を取得します。
57        foreach ($reflectionClass->getProperties() as $property) {
58            $propertyName = $property->getName();
59
60            // ReflectionProperty::getDocComment() を使用して、
61            // プロパティに記述されたPHPDocコメントを文字列として取得します。
62            // コメントがない場合は false が返されます。
63            $docComment = $property->getDocComment();
64
65            echo "プロパティ名: '{$propertyName}'" . PHP_EOL;
66
67            if ($docComment !== false) {
68                echo "  Docコメント:" . PHP_EOL;
69                echo $docComment . PHP_EOL; // 取得したコメントを出力
70            } else {
71                echo "  Docコメント: このプロパティにはDocコメントがありません。" . PHP_EOL;
72            }
73            echo PHP_EOL; // 各プロパティの出力を見やすくするための改行
74        }
75    } catch (ReflectionException $e) {
76        // クラスが見つからない場合などに発生するエラーを捕捉します。
77        echo "エラー: クラス '{$className}' の情報を取得できませんでした。- " . $e->getMessage() . PHP_EOL;
78    }
79}
80
81// 上で定義したUserProfileクラスに対して、プロパティのDocコメントを表示します。
82showPropertyDocComments(UserProfile::class);
83
84?>

PHPのReflectionProperty::getDocComment()メソッドは、クラスのプロパティ（変数）に記述されたPHPDocコメントを文字列として取得するための機能です。PHPのReflection APIの一部であり、実行時にクラスやプロパティの構造を動的に調べることができます。

このメソッドは引数を必要としません。プロパティにPHPDocコメントが記述されていれば、そのコメント全体を文字列として返します。もし該当するプロパティにPHPDocコメントが存在しない場合は、falseが戻り値として返されます。これにより、プログラムは特定のプロパティが持つコメントの有無を判別し、その内容を処理することが可能になります。

提供されたサンプルコードでは、UserProfileクラスが定義されており、そのプロパティの一部（idやname）にはPHPDocコメントが記述されていますが、emailAddressプロパティには記述されていません。showPropertyDocComments関数は、ReflectionClassを利用してUserProfileクラスの情報を取得し、各プロパティに対してReflectionProperty::getDocComment()を呼び出しています。結果として、コメントが記述されたプロパティからはその内容が表示され、コメントがないemailAddressプロパティからは「Docコメントがありません」と出力される様子を確認できます。この機能は、コードの自動文書化や開発ツールによる解析、検証などに活用されます。

Copy
1<?php
2
3/**
4 * このサンプルクラスは、プロパティに付与されたPHPDocコメントの抽出例を示します。
5 */
6class MyDataClass
7{
8    /**
9     * @var string ユーザーの名前。公開プロパティ。
10     *             複数行にわたるコメントの例です。
11     */
12    public string $userName;
13
14    /**
15     * @var int ユーザーの一意な識別子。保護されたプロパティ。
16     */
17    protected int $userId;
18
19    // このプロパティにはPHPDocコメントがありません。
20    public bool $isActive = false;
21
22    /**
23     * @var array ユーザーが保持する権限のリスト。
24     */
25    private array $permissions = [];
26
27    /**
28     * コンストラクタ。
29     *
30     * @param string $userName ユーザーの名前
31     * @param int $userId ユーザーID
32     */
33    public function __construct(string $userName, int $userId)
34    {
35        $this->userName = $userName;
36        $this->userId = $userId;
37    }
38}
39
40/**
41 * 指定されたクラスのすべてのプロパティからPHPDocコメントを抽出し、表示する関数です。
42 * システムエンジニアを目指す初心者向けに、PHPDocを読み取る基本的な方法を示します。
43 *
44 * @param string $className コメントを抽出する対象のクラス名。例: MyDataClass::class
45 * @return void
46 */
47function displayPropertyDocComments(string $className): void
48{
49    echo "--- クラス: {$className} のプロパティPHPDocコメントを抽出 ---\n";
50
51    try {
52        // ReflectionClassを使用して、指定されたクラスの情報を取得します。
53        $reflectionClass = new ReflectionClass($className);
54
55        // クラスが持つすべてのプロパティを取得します。
56        // getProperties() は ReflectionProperty オブジェクトの配列を返します。
57        foreach ($reflectionClass->getProperties() as $property) {
58            // 各プロパティの名前を表示します。
59            echo "プロパティ名: {$property->getName()}\n";
60
61            // ReflectionProperty::getDocComment() メソッドを呼び出します。
62            // このメソッドは、プロパティに記述されたPHPDocコメントの文字列を返します。
63            // コメントが存在しない場合は 'false' を返します。
64            $docComment = $property->getDocComment();
65
66            if ($docComment === false) {
67                echo "  PHPDocコメント: なし\n";
68            } else {
69                // 取得したコメントを表示します。
70                // 通常、取得されるコメントはPHPのPHPDoc形式で整形されています。
71                echo "  PHPDocコメント:\n{$docComment}\n";
72            }
73            echo "----------------------------------------\n";
74        }
75    } catch (ReflectionException $e) {
76        // クラスが見つからない場合などに発生するエラーを捕捉します。
77        echo "エラー: クラス '{$className}' が見つかりません。 " . $e->getMessage() . "\n";
78    }
79}
80
81// MyDataClass のプロパティPHPDocコメントを抽出して表示します。
82displayPropertyDocComments(MyDataClass::class);

このPHPのサンプルコードは、PHP 8で利用可能な「リフレクションAPI」を活用し、クラスのプロパティに付与された「PHPDocコメント」をプログラムから動的に読み取る方法を、システムエンジニアを目指す初心者にも分かりやすく示しています。

中心となるのは、ReflectionPropertyクラスのgetDocComment()メソッドです。このメソッドは引数を一切取らずに呼び出すことができ、対象のプロパティに記述されているPHPDocコメントの内容を文字列として返します。もし該当するPHPDocコメントが存在しない場合は、戻り値としてfalseを返します。

サンプルコードでは、まずReflectionClassを用いて指定されたクラスの情報を取得します。次に、getProperties()メソッドでそのクラスに定義されているすべてのプロパティ情報を一つずつReflectionPropertyオブジェクトとして取り出しています。それぞれのプロパティに対してgetDocComment()メソッドを実行し、コメントの有無を確認してその内容を出力しています。

このようにPHPDocコメントをプログラムで取得する機能は、「phpdoc generator」のような自動ドキュメント生成ツールや、コードの静的解析ツールなどの開発に非常に役立ちます。PHPDocコメントはコードの意図を明確にし、開発効率と可読性を高める上で重要な役割を担っています。