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

Copy
1<?php
2
3/**
4 * このクラスは、PHPの ReflectionClass::getDocComment() メソッドの
5 * 使用例を示すためのサンプルクラスです。
6 *
7 * PHPDocコメントは、クラス、メソッド、プロパティなどの目的や
8 * 使い方を説明するために利用されます。
9 *
10 * @package ReflectionDemo
11 * @category Example
12 * @author   Sample Author <sample@example.com>
13 * @version  1.0.0
14 */
15class MyDocumentedClass
16{
17    /**
18     * このプロパティは、クラスのメッセージを保持します。
19     * @var string メッセージの内容
20     */
21    public string $message = 'Hello Reflection!';
22
23    /**
24     * MyDocumentedClass の新しいインスタンスを作成します。
25     *
26     * @param string $initialMessage プロパティの初期メッセージ（オプション）
27     */
28    public function __construct(string $initialMessage = '')
29    {
30        if ($initialMessage) {
31            $this->message = $initialMessage;
32        }
33    }
34
35    /**
36     * 現在のメッセージを取得します。
37     *
38     * @return string クラスが保持するメッセージ
39     */
40    public function getMessage(): string
41    {
42        return $this->message;
43    }
44}
45
46// ReflectionClass を使って MyDocumentedClass の情報を取得します。
47// これにより、クラスの構造やそのPHPDocコメントなどのメタデータにアクセスできます。
48$reflector = new ReflectionClass(MyDocumentedClass::class);
49
50// getDocComment() メソッドを呼び出し、クラス全体に記述された PHPDoc コメントを取得します。
51// コメントがない場合、このメソッドは false を返します。
52$docComment = $reflector->getDocComment();
53
54// 取得したドキュメントコメントを表示します。
55// false でないことを確認することで、コメントが存在するかどうかを判断できます。
56if ($docComment !== false) {
57    echo "--- MyDocumentedClass のドキュメントコメント ---\n";
58    echo $docComment . "\n";
59} else {
60    echo "MyDocumentedClass にはドキュメントコメントがありません。\n";
61}

PHP 8 の ReflectionClass::getDocComment() メソッドは、指定されたクラスに記述された PHPDoc コメントを取得するために利用されます。まず、ReflectionClass クラスのインスタンスを作成し、調べたいクラスの情報を取得する必要があります。ReflectionClass は、プログラムの実行中にクラスやそのメンバー（メソッド、プロパティなど）の構造に関するメタデータ（付加情報）を動的に調べることができる機能を提供します。

getDocComment() メソッドは引数を持ちません。このメソッドを呼び出すと、クラス定義の直前に記述された PHPDoc コメントの内容が文字列として返されます。もし該当するPHPDocコメントが存在しない場合は、戻り値としてfalseが返されます。

サンプルコードでは、MyDocumentedClass のクラス定義の上に書かれた PHPDoc コメントを ReflectionClass を通じて取得し、その内容を表示しています。これにより、クラスの目的や利用方法などのドキュメント情報をプログラムから動的に読み取ることが可能になります。戻り値がfalseでないことを確認することで、コメントが存在するかどうかを判断できます。この機能は、自動的なドキュメント生成やフレームワークでのクラス解析など、様々な場面で活用されます。

Copy
1<?php
2
3/**
4 * このクラスは、システム内でユーザー情報を管理するための基本的なモデルを表します。
5 * PHPDocコメントの読み取りの例として使用されます。
6 *
7 * @package App\Models
8 * @author 開発者A <developer.a@example.com>
9 * @version 1.0.0
10 * @see \ReflectionClass
11 */
12class UserProfile
13{
14    /**
15     * ユーザーのユニークなIDです。
16     * @var int
17     */
18    private int $id;
19
20    /**
21     * ユーザー名です。
22     * @var string
23     */
24    private string $name;
25
26    /**
27     * 新しいUserProfileインスタンスを作成します。
28     *
29     * @param int $id ユーザーID
30     * @param string $name ユーザー名
31     */
32    public function __construct(int $id, string $name)
33    {
34        $this->id = $id;
35        $this->name = $name;
36    }
37
38    /**
39     * ユーザーのフルネームを取得します。
40     * @return string
41     */
42    public function getFullName(): string
43    {
44        return $this->name;
45    }
46}
47
48/**
49 * 指定されたクラスのPHPDocコメントを抽出し、表示する関数です。
50 * これはPHPDocジェネレーターが情報を収集する際の基本的なステップを示します。
51 *
52 * @param string $className PHPDocコメントを抽出したいクラスの完全修飾名
53 * @return void
54 */
55function extractAndDisplayClassDocComment(string $className): void
56{
57    try {
58        // ReflectionClassのインスタンスを作成
59        $reflectionClass = new ReflectionClass($className);
60
61        // getDocComment()メソッドを呼び出してPHPDocコメントを取得
62        $docComment = $reflectionClass->getDocComment();
63
64        if ($docComment !== false) {
65            echo "--- クラス '{$className}' のPHPDocコメント ---\n";
66            echo $docComment . "\n";
67            echo "--------------------------------------------------\n";
68        } else {
69            echo "クラス '{$className}' にはPHPDocコメントが定義されていません。\n";
70        }
71    } catch (ReflectionException $e) {
72        // クラスが存在しない場合の例外処理
73        echo "エラー: クラス '{$className}' が見つかりません。詳細: " . $e->getMessage() . "\n";
74    }
75}
76
77// UserProfileクラスのPHPDocコメントを抽出して表示
78extractAndDisplayClassDocComment(UserProfile::class);
79
80// PHPDocコメントがないクラスの例
81class SimpleClassWithoutDocComment {}
82extractAndDisplayClassDocComment(SimpleClassWithoutDocComment::class);
83
84// 存在しないクラス名を渡した場合の例
85// extractAndDisplayClassDocComment('NonExistentClass');
86
87?>

PHP 8のReflectionClass::getDocCommentメソッドは、プログラム実行時にクラスの情報を動的に取得・分析できるリフレクション機能の一部です。このメソッドは、クラス定義の上部に記述された特別な形式のコメント、PHPDocコメントを読み取るために使用されます。PHPDocコメントは、コードの目的、使い方、バージョン、作者などを開発者にわかりやすく説明する役割があり、ドキュメント自動生成ツール（PHPDocジェネレーターなど）がソースコードから情報を抽出する際に活用されます。

このメソッドは引数を必要とせず、もし対象のクラスにPHPDocコメントが記述されていれば、その内容を文字列として返します。コメントが存在しない場合はfalseを返します。

サンプルコードでは、まずPHPDocコメントが詳細に記述されたUserProfileクラスを定義しています。次に、extractAndDisplayClassDocComment関数が、指定されたクラス名をもとにReflectionClassのインスタンスを作成し、getDocComment()メソッドを呼び出してクラスのPHPDocコメントを取得しています。取得したコメントは画面に表示され、コメントがないクラスや存在しないクラス名が指定された場合の挙動も確認できます。これにより、プログラムがコードのメタデータ（付帯情報）を読み取れる仕組みが示されています。