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

Copy
1<?php
2
3/**
4 * カスタム属性の定義。
5 * パラメータに適用されることを指定します。
6 */
7#[Attribute(Attribute::TARGET_PARAMETER)]
8class MyParameterDescription
9{
10    public string $description;
11
12    /**
13     * @param string $description このパラメータの簡潔な説明
14     */
15    public function __construct(string $description)
16    {
17        $this->description = $description;
18    }
19}
20
21/**
22 * 属性が適用されたパラメータを持つサンプルクラス。
23 */
24class SystemService
25{
26    /**
27     * システム内でユーザーデータを処理するメソッド。
28     * 各パラメータには、その役割を説明する属性が付与されています。
29     *
30     * @param int    $userId    処理するユーザーのID
31     * @param string $operation 実行する操作のタイプ
32     */
33    public function processUserData(
34        #[MyParameterDescription("処理対象のユーザーID")]
35        int $userId,
36        #[MyParameterDescription("実行する操作の名称 (例: 'update', 'delete')")]
37        string $operation
38    ): void {
39        echo "Processing user ID: {$userId} for operation: {$operation}\n";
40    }
41}
42
43// ReflectionClass を使用してSystemServiceクラスの情報を取得します。
44$reflectionClass = new ReflectionClass(SystemService::class);
45
46// processUserData メソッドのReflectionMethodオブジェクトを取得します。
47$reflectionMethod = $reflectionClass->getMethod('processUserData');
48
49echo "--- メソッド '{$reflectionMethod->getName()}' のパラメータ属性を解析中 ---\n\n";
50
51// メソッドの各パラメータをループし、その属性を取得します。
52foreach ($reflectionMethod->getParameters() as $parameter) {
53    echo "パラメータ名: {$parameter->getName()}\n";
54    echo "パラメータ型: " . ($parameter->getType() ? $parameter->getType()->getName() : '不明') . "\n";
55
56    // ReflectionParameter::getAttributes() を使用して、パラメータに付与されたすべての属性を取得します。
57    // 引数なしで呼び出すと、すべての型の属性が返されます。
58    $attributes = $parameter->getAttributes();
59
60    if (empty($attributes)) {
61        echo "  このパラメータには属性が見つかりませんでした。\n";
62    } else {
63        echo "  見つかった属性 ({$parameter->getName()}): " . count($attributes) . "個\n";
64        foreach ($attributes as $attribute) {
65            // 属性のクラス名を出力します。
66            echo "    属性クラス名: {$attribute->getName()}\n";
67
68            // 属性のインスタンスを作成し、そのプロパティにアクセスします。
69            $attributeInstance = $attribute->newInstance();
70
71            // カスタム属性 MyParameterDescription のインスタンスであるか確認し、説明を出力します。
72            if ($attributeInstance instanceof MyParameterDescription) {
73                echo "    説明: {$attributeInstance->description}\n";
74            }
75        }
76    }
77    echo "\n";
78}
79
80// 実際にメソッドを呼び出してみる
81echo "--- メソッドの実行例 ---\n";
82$service = new SystemService();
83$service->processUserData(123, 'update');
84
85?>

このサンプルコードは、PHP 8で導入された「属性（Attributes）」と「リフレクションAPI」を組み合わせ、メソッドのパラメータに関する追加情報（メタデータ）をプログラムの実行時に動的に読み取る方法を示しています。

まず、MyParameterDescription クラスは、パラメータに説明を付与するためのカスタム属性として定義されています。#[Attribute(Attribute::TARGET_PARAMETER)] は、この属性がクラスのプロパティやメソッド全体ではなく、特定のパラメータにのみ適用できることを示しています。 SystemService クラスの processUserData メソッドでは、そのパラメータである $userId と $operation に、この MyParameterDescription 属性を使って、それぞれの詳細な役割がコード上に直接記述されています。

コードの後半では、ReflectionClass と ReflectionMethod を使用して、SystemService クラスとその processUserData メソッドの情報を取得しています。 そして、このメソッドの各パラメータに対し、ReflectionParameter::getAttributes() メソッドを呼び出しています。このメソッドは、指定されたパラメータに付与されたすべての属性を取得するために使用されます。引数 $name を指定すると特定の名前の属性のみを、$flags を指定すると特定の条件に一致する属性のみをフィルタリングできますが、サンプルでは引数なしで呼び出しているため、すべての属性が配列として戻り値として返されます。 戻り値の配列に含まれる ReflectionAttribute オブジェクトからは、getName() で属性のクラス名を取得したり、newInstance() で属性クラスのインスタンスを生成して、属性に設定された具体的な値（この例では description プロパティ）にアクセスしたりすることが可能です。

このように、ReflectionParameter::getAttributes() を使うことで、実行時にコードの構造だけでなく、それに付与された詳細なメタデータも検査し、プログラムの振る舞いを柔軟に制御できるようになります。

Copy
1<?php
2
3/**
4 * パラメータに適用するためのカスタム属性を定義します。
5 * #[Attribute(Attribute::TARGET_PARAMETER)] を使用して、この属性がパラメータにのみ
6 * 付与できることを指定します。
7 *
8 * システムエンジニアを目指す初心者の方へ:
9 * 属性 (Attributes) は、PHP 8で導入されたメタデータをコードに付与する機能です。
10 * これにより、クラス、メソッド、関数、プロパティ、パラメータなどに、追加の情報を
11 * コードを変更せずに付与できます。リフレクションAPIを使うことで、実行時にこれらの
12 * 属性情報を読み取ることが可能になります。
13 */
14#[Attribute(Attribute::TARGET_PARAMETER)]
15class Description
16{
17    /**
18     * 属性のコンストラクタ。属性が使用される際に引数を渡すことができます。
19     *
20     * @param string $text この属性が持つ説明文。
21     */
22    public function __construct(
23        public string $text
24    ) {}
25}
26
27/**
28 * 属性が付与されたパラメータを持つサンプル関数。
29 *
30 * @param string $name ユーザーの名前。Description属性が付与されています。
31 * @param int $age ユーザーの年齢。このパラメータには属性は付与されていません。
32 */
33function showUserInfo(
34    #[Description('ユーザーのフルネーム')] string $name,
35    int $age
36): void {
37    echo "ユーザー名: {$name}, 年齢: {$age}\n";
38}
39
40// ReflectionFunctionオブジェクトを作成し、showUserInfo関数のリフレクション情報を取得
41$reflectionFunction = new ReflectionFunction('showUserInfo');
42
43echo "--- 関数 'showUserInfo' のパラメータ属性情報を取得 ---\n\n";
44
45// 関数の各パラメータについてループ
46foreach ($reflectionFunction->getParameters() as $parameter) {
47    echo "パラメータ名: " . $parameter->getName() . "\n";
48
49    // ReflectionParameter::getAttributes() を使用して、現在のパラメータに付与された
50    // すべての属性 (ReflectionAttributeオブジェクトの配列) を取得します。
51    // 引数を指定しない場合、すべての属性が返されます。
52    // 例: $parameter->getAttributes(Description::class) とすると、
53    // Descriptionクラスの属性のみをフィルタリングして取得できます。
54    $attributes = $parameter->getAttributes();
55
56    if (empty($attributes)) {
57        echo "  -> 属性: なし\n";
58    } else {
59        echo "  -> 属性:\n";
60        foreach ($attributes as $attribute) {
61            echo "    - 属性クラス名: " . $attribute->getName() . "\n";
62
63            // getAttributesで取得したReflectionAttributeオブジェクトから
64            // newInstance() を呼び出すことで、実際の属性クラスのインスタンスを生成できます。
65            // これにより、属性に渡されたコンストラクタ引数（例: Descriptionの$text）にアクセスできます。
66            $attributeInstance = $attribute->newInstance();
67            if ($attributeInstance instanceof Description) {
68                echo "      説明テキスト: " . $attributeInstance->text . "\n";
69            }
70        }
71    }
72    echo "\n";
73}
74
75?>

PHPのReflectionParameter::getAttributesメソッドは、関数の引数（パラメータ）に付与された「属性（Attributes）」という追加情報を取り出すために使用されます。属性はPHP 8で導入された機能で、クラス、メソッド、パラメータといったコードの要素に対して、コードの動作を変えることなく追加の情報を埋め込むことができるメタデータのことです。リフレクションAPIと組み合わせることで、プログラムの実行時にこれらの属性情報を読み取ることが可能になります。

このサンプルコードでは、まずDescriptionというカスタム属性を定義し、これがパラメータにのみ適用されるよう指定しています。次に、showUserInfo関数を作成し、その$nameパラメータに#[Description('ユーザーのフルネーム')]という形で、定義したDescription属性を付与しています。$ageパラメータには属性は付与されていません。

コードの実行部では、ReflectionFunctionオブジェクトを使ってshowUserInfo関数のリフレクション情報を取得し、その中の各パラメータについてループしています。$parameter->getAttributes()を呼び出すことで、現在のパラメータ（例えば$name）に付与されているすべての属性情報を取得しています。このメソッドは、ReflectionAttributeオブジェクトの配列を戻り値として返します。

引数$nameに属性クラス名（例: Description::class）を指定することで、特定の属性のみをフィルタリングして取得できます。$flags引数は将来的な拡張のために予約されています。取得したReflectionAttributeオブジェクトからnewInstance()メソッドを使って実際の属性クラス（この場合はDescription）のインスタンスを生成し、属性が持つ値（Descriptionクラスの$textプロパティ）にアクセスできることを示しています。これにより、実行時にパラメータのメタデータを柔軟に処理することが可能となります。