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

Copy
1<?php
2
3/**
4 * 与えられた名前でユーザーに挨拶のメッセージを生成します。
5 *
6 * この関数は、システムエンジニアを目指す初心者が
7 * PHPのリフレクション機能を使ってドキュメンテーションコメント
8 * (PHPDoc) を取得する方法を学ぶための例です。
9 *
10 * @param string $name 挨拶する対象の名前。
11 * @return string 生成された挨拶のメッセージ。
12 */
13function generateGreeting(string $name): string
14{
15    return "こんにちは、" . $name . "さん！";
16}
17
18// ドキュメンテーションコメントを取得したい関数の名前を指定します。
19$functionName = 'generateGreeting';
20
21try {
22    // ReflectionFunction クラスのインスタンスを作成し、
23    // 指定された関数に関する情報を「リフレクション」（実行時に取得）します。
24    $reflectionFunction = new ReflectionFunction($functionName);
25
26    // ReflectionFunctionAbstract クラスの getDocComment() メソッドを呼び出し、
27    // 関数のドキュメンテーションコメント（PHPDoc）を取得します。
28    // コメントが存在しない場合は false を返します。
29    $docComment = $reflectionFunction->getDocComment();
30
31    if ($docComment !== false) {
32        echo "関数 '{$functionName}' のドキュメンテーションコメント:\n";
33        echo $docComment . "\n";
34    } else {
35        echo "関数 '{$functionName}' にはドキュメンテーションコメントが見つかりませんでした。\n";
36    }
37} catch (ReflectionException $e) {
38    // 指定された関数が見つからないなどのエラーが発生した場合に、
39    // エラーメッセージを出力します。
40    echo "エラー: " . $e->getMessage() . "\n";
41}
42

このPHPのサンプルコードは、「リフレクション」という機能を使って、プログラムの実行中に定義された関数の「ドキュメンテーションコメント」（PHPDoc）を取得する方法を示しています。ドキュメンテーションコメントは、関数が何をするのか、どのような引数を受け取り、何を返すのかといった情報を開発者向けに記述する重要な部分です。

まず、generateGreetingという関数が定義されており、その上に具体的なPHPDocが記述されています。

コードは、ReflectionFunctionクラスのインスタンスを作成することで、generateGreeting関数に関する情報を実行時に「リフレクション」（反映）しています。その後、このReflectionFunctionインスタンスのgetDocComment()メソッドを呼び出しています。このメソッドは引数を取らず、対象の関数に記述されたドキュメンテーションコメントを文字列として返します。もしコメントが存在しない場合はfalseを返します。

取得した値がfalseでなければ、そのコメントの内容を出力します。もしfalseが返された場合は、対象の関数にドキュメンテーションコメントが見つからなかったことを表示します。

また、try-catchブロックを用いて、指定された関数が存在しないといったエラーが発生した場合に、ReflectionExceptionを捕捉し、適切なエラーメッセージを表示するようにしています。この機能は、コードの自動解析ツールや、ドキュメント生成ツールなどで活用されます。

Copy
1<?php
2
3/**
4 * 2つの数値を加算する関数です。
5 *
6 * この関数は、与えられた2つの数値を加算し、その結果を返します。
7 * PHPDocコメントの解析例として使用されます。
8 *
9 * @param int $a 最初の数値
10 * @param int $b 2番目の数値
11 * @return int 2つの数値の合計
12 */
13function addNumbers(int $a, int $b): int
14{
15    return $a + $b;
16}
17
18/**
19 * 指定された関数のPHPDocコメントを取得し、その内容を解析して表示する関数。
20 *
21 * Reflection APIを使用して関数のドキュメントコメントを読み込み、
22 * PHPDocの概要、パラメータ、戻り値の情報を抽出し、整形して表示します。
23 * これにより、PHPDocコメントからドキュメント情報を「生成」する例を示します。
24 *
25 * @param string $functionName 解析対象の関数名
26 * @return void
27 */
28function generatePhpDocInfo(string $functionName): void
29{
30    try {
31        // ReflectionFunctionオブジェクトを作成し、関数のメタデータにアクセスします。
32        $reflectionFunction = new ReflectionFunction($functionName);
33
34        // getDocComment() メソッドでPHPDocコメントを取得します。
35        // コメントがない場合は false を返します。
36        $docComment = $reflectionFunction->getDocComment();
37
38        echo "--- 関数 '{$functionName}' のPHPDoc情報 --- \n";
39
40        if ($docComment === false) {
41            echo "  この関数にはPHPDocコメントがありません。\n";
42            echo "----------------------------------------\n";
43            return;
44        }
45
46        // 取得したPHPDocコメントをそのまま表示
47        echo "生PHPDocコメント:\n";
48        echo "{$docComment}\n";
49
50        echo "解析されたPHPDoc情報:\n";
51
52        // PHPDocコメントを改行で分割し、行ごとに処理
53        $lines = explode("\n", $docComment);
54        $summary = '';
55        $params = [];
56        $return = '';
57
58        foreach ($lines as $line) {
59            // 各行からコメントブロックの「*」や先頭・末尾のスペースを除去
60            $trimmedLine = trim($line, " \t/*");
61
62            if ($trimmedLine === '') {
63                continue; // 空行はスキップ
64            }
65
66            // '@'で始まる行はPHPDocタグとして処理
67            if (str_starts_with($trimmedLine, '@param')) {
68                // @param タグから型、変数名、説明を抽出
69                if (preg_match('/^@param\s+(?<type>\S+)\s+\$(?<name>\S+)\s*(?<description>.*)/', $trimmedLine, $matches)) {
70                    $params[] = "  - \${$matches['name']} ({$matches['type']}): {$matches['description']}";
71                }
72            } elseif (str_starts_with($trimmedLine, '@return')) {
73                // @return タグから型と説明を抽出
74                if (preg_match('/^@return\s+(?<type>\S+)\s*(?<description>.*)/', $trimmedLine, $matches)) {
75                    $return = "  戻り値 ({$matches['type']}): {$matches['description']}";
76                }
77            } elseif ($summary === '' && !str_starts_with($trimmedLine, '@')) {
78                // まだ概要が設定されておらず、かつPHPDocタグでない行は概要と見なす
79                $summary = $trimmedLine;
80            }
81        }
82
83        // 抽出した情報を表示
84        if ($summary !== '') {
85            echo "  概要: {$summary}\n";
86        }
87
88        if (!empty($params)) {
89            echo "  パラメータ:\n";
90            foreach ($params as $param) {
91                echo $param . "\n";
92            }
93        }
94
95        if ($return !== '') {
96            echo $return . "\n";
97        }
98
99        echo "----------------------------------------\n";
100
101    } catch (ReflectionException $e) {
102        // 指定された関数が見つからない場合のエラーハンドリング
103        echo "エラー: 関数 '{$functionName}' が見つかりません。 - " . $e->getMessage() . "\n";
104        echo "----------------------------------------\n";
105    }
106}
107
108// PHPDocコメントを持つ関数の情報を生成して表示
109generatePhpDocInfo('addNumbers');
110
111echo "\n";
112
113// PHPDocコメントを持たない関数の例
114function noDocCommentFunction(string $name): string
115{
116    return "Hello, " . $name . "!";
117}
118
119// PHPDocコメントを持たない関数の情報を生成して表示
120generatePhpDocInfo('noDocCommentFunction');
121
122echo "\n";
123
124// 存在しない関数の情報を生成しようとする例
125generatePhpDocInfo('nonExistentFunction');

PHP 8のリフレクションAPIにあるReflectionFunctionAbstract::getDocCommentメソッドは、関数やメソッドに記述されたPHPDocコメントを取得するために使用されます。このメソッドは、ReflectionFunctionクラスやReflectionMethodクラスなど、ReflectionFunctionAbstractを継承するクラスのインスタンスから呼び出されます。

引数は不要で、呼び出すだけで対象のPHPDocコメントを文字列として返します。もし該当する関数やメソッドにPHPDocコメントが記述されていない場合は、falseが戻り値として返されます。これにより、コメントの有無を簡単に判別できます。

このサンプルコードでは、PHPDocコメントを持つaddNumbers関数を定義しています。generatePhpDocInfo関数では、指定された関数名でReflectionFunctionオブジェクトを作成し、getDocCommentメソッドでコメントを取得します。取得したPHPDocコメントの文字列を解析し、関数の概要、パラメータ、戻り値といった情報を抽出して表示しています。これは、PHPDocコメントからドキュメントを自動生成するツール（phpdoc generator）の基盤となる仕組みを理解する良い例です。コメントがない場合や関数が見つからない場合のエラー処理も含まれており、その具体的な使い方や応用方法を学ぶことができます。