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

Copy
1<?php
2
3/**
4 * このクラスは、メソッドのDocComment（PHPDoc）を取得するデモンストレーションに使用されます。
5 * システムエンジニアにとって、DocCommentはコードの目的や使い方を理解する上で非常に重要な情報です。
6 */
7class ProductService
8{
9    /**
10     * 指定されたIDに基づいて製品情報を取得します。
11     *
12     * このDocCommentは、メソッドの機能、引数、および戻り値について説明しています。
13     * リフレクションAPIの getDocComment() メソッドを使用すると、
14     * プログラム実行時にこのコメントの内容を読み取ることができます。
15     *
16     * @param int $productId 取得する製品のユニークなID
17     * @return array|null 製品の連想配列データ、または製品が見つからない場合はnull
18     */
19    public function getProductById(int $productId): ?array
20    {
21        // ここでは実際のデータベース操作などは行わず、
22        // 例として固定のデータを返します。
23        $products = [
24            101 => ['name' => 'Laptop', 'price' => 1200],
25            102 => ['name' => 'Mouse', 'price' => 25],
26        ];
27
28        return $products[$productId] ?? null;
29    }
30}
31
32// ReflectionMethod クラスのインスタンスを作成し、ProductService クラスの getProductById メソッドを参照します。
33// これにより、メソッドの構造や属性（DocCommentを含む）にプログラムからアクセスできるようになります。
34$reflectionMethod = new ReflectionMethod('ProductService', 'getProductById');
35
36// getDocComment() メソッドを呼び出して、getProductById メソッドに記述されたDocCommentを取得します。
37// このメソッドは、DocCommentが存在しない場合は false を、存在する場合は文字列を返します。
38$docComment = $reflectionMethod->getDocComment();
39
40// 取得したDocCommentの内容を出力します。
41echo "--- 'getProductById' メソッドのDocComment ---\n";
42if ($docComment !== false) {
43    echo $docComment . "\n";
44} else {
45    echo "DocCommentが見つかりませんでした。\n";
46}
47
48?>

このサンプルコードは、PHPのReflectionMethod::getDocComment()メソッドを使用し、クラスのメソッドに記述されたDocComment（PHPDoc）をプログラム実行時に取得する方法を示しています。DocCommentは、メソッドの機能や引数、戻り値などを開発者が記述するための標準的なコメント形式であり、コードの可読性やメンテナンス性を高める上で非常に重要な情報です。

まず、ProductServiceクラスとその中に定義されたgetProductByIdメソッドでは、そのメソッドが何をするのか、どのような引数をとり、何を返すのかを明確に記述したDocCommentが設けられています。

次に、ReflectionMethodクラスのインスタンスを作成します。これは、特定のクラスのメソッドに関する構造や属性（DocCommentを含む）を動的に調べるためのPHPの機能です。インスタンスは、対象となるクラス名とメソッド名を指定して生成します。

作成した$reflectionMethodインスタンスからgetDocComment()メソッドを呼び出すことで、getProductByIdメソッドのDocCommentを取得します。このメソッドは引数を取りません。DocCommentが存在する場合はその内容を文字列として返し、存在しない場合はfalseを返します。

最後に、取得した$docCommentの内容を出力しています。falseでないことを確認してから内容を表示することで、DocCommentが見つからないケースにも対応しています。システムエンジニアにとって、このようにプログラムからコードのメタ情報を取得するリフレクション機能は、ドキュメント生成ツールやフレームワークの内部処理などで活用できる強力な機能です。

Copy
1<?php
2
3/**
4 * このクラスは、リフレクションAPIを使用してメソッドのPHPDocコメントを
5 * 取得する例を示すために定義されています。
6 */
7class Calculator
8{
9    /**
10     * 2つの数値を加算し、その結果を返します。
11     *
12     * このメソッドは、与えられた2つの整数または浮動小数点数を合計します。
13     * PHPDocコメントは、メソッドの目的、引数、および戻り値の型を記述し、
14     * ドキュメント生成ツール（phpDocumentorなど）によって利用されます。
15     *
16     * @param float|int $num1 加算する最初の数値。
17     * @param float|int $num2 加算する2番目の数値。
18     * @return float|int 2つの数値の合計。
19     */
20    public function add(float|int $num1, float|int $num2): float|int
21    {
22        return $num1 + $num2;
23    }
24
25    /**
26     * このメソッドには、意図的に簡潔なPHPDocコメントしかありません。
27     */
28    public function subtract(float|int $num1, float|int $num2): float|int
29    {
30        return $num1 - $num2;
31    }
32
33    // このメソッドにはPHPDocコメントがありません。
34    // ReflectionMethod::getDocComment() を呼び出すと false が返されます。
35    public function multiply(float|int $num1, float|int $num2): float|int
36    {
37        return $num1 * $num2;
38    }
39}
40
41// ReflectionMethod クラスのインスタンスを作成し、
42// 'Calculator' クラスの 'add' メソッドのリフレクション情報を取得します。
43// 第1引数にクラス名、第2引数にメソッド名を指定します。
44$reflectionMethod = new ReflectionMethod(Calculator::class, 'add');
45
46// getDocComment() メソッドを呼び出し、PHPDocコメントの文字列を取得します。
47// メソッドにPHPDocコメントが存在しない場合は、false が返されます。
48$docComment = $reflectionMethod->getDocComment();
49
50// 取得したPHPDocコメントを出力します。
51if ($docComment !== false) {
52    echo "--- 'add' メソッドのPHPDocコメント ---\n";
53    echo $docComment . "\n";
54} else {
55    echo "--- 'add' メソッドにはPHPDocコメントが見つかりませんでした ---\n";
56}
57
58// PHPDocコメントがないメソッドの例
59$reflectionMethodNoDoc = new ReflectionMethod(Calculator::class, 'multiply');
60$docCommentNoDoc = $reflectionMethodNoDoc->getDocComment();
61
62if ($docCommentNoDoc !== false) {
63    echo "\n--- 'multiply' メソッドのPHPDocコメント ---\n";
64    echo $docCommentNoDoc . "\n";
65} else {
66    echo "\n--- 'multiply' メソッドにはPHPDocコメントが見つかりませんでした ---\n";
67}
68

PHPのReflectionMethod::getDocCommentメソッドは、クラスのメソッドに記述されたPHPDocコメントを文字列として取得する機能を提供します。PHPDocコメントは、メソッドの目的、引数、戻り値の型といった詳細な情報を記述するための標準的な形式です。これはphpDocumentorのようなドキュメント生成ツールによって利用され、コードの可読性や保守性を高める役割を果たします。

このメソッドは引数を必要としません。対象のメソッドにPHPDocコメントが存在する場合、そのコメント全体が文字列として返されます。もしPHPDocコメントが記述されていない場合は、falseが戻り値となります。

サンプルコードでは、まずCalculatorクラスのaddメソッドからPHPDocコメントを取得する例を示しています。addメソッドにはコメントが完全に記述されているため、その内容が正確に取得され、表示されます。一方で、PHPDocコメントが存在しないmultiplyメソッドに対して同じメソッドを呼び出すと、falseが返される挙動が確認できます。このように、プログラム実行時にメソッドのドキュメント情報を動的に調べたい場合に、このgetDocCommentメソッドが非常に役立ちます。