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

Copy
1<?php
2
3// --- 属性の定義 ---
4
5// 1. 本来は単一インスタンスとして使用されるべきだが、
6//    誤って Attribute::IS_REPEATABLE フラグが設定されている属性を想定。
7//    `isRepeated()` が `true` を返すことが「設定上のエラー」につながる状況を示します。
8#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
9class SingleConfigAttribute
10{
11    public function __construct(public string $settingName) {}
12}
13
14// 2. 複数回適用されることが期待される（例: ログ）が、
15//    Attribute::IS_REPEATABLE フラグが忘れられている属性を想定。
16//    `isRepeated()` が `false` を返すことが「設定漏れ」につながる状況を示します。
17#[Attribute(Attribute::TARGET_CLASS)] // IS_REPEATABLE はデフォルトで false です
18class LogEventAttribute
19{
20    public function __construct(public string $eventName) {}
21}
22
23// --- 監査対象のクラス ---
24// このクラスに適用された属性の定義を監査します。
25#[SingleConfigAttribute("database_connection")]
26// SingleConfigAttribute は IS_REPEATABLE で定義されているため、複数回適用できます。
27// ここではその定義自体がビジネスルールと合致しているかを監査します。
28#[SingleConfigAttribute("cache_settings")]
29#[LogEventAttribute("Application startup")]
30// LogEventAttribute は IS_REPEATABLE でないため、PHP 8.1+ では2つ目以降は無視されます（PHP 8.0 ではエラー）。
31// ここではその定義自体がビジネスルールと合致しているかを監査します。
32#[LogEventAttribute("Database check")]
33class SystemService
34{
35    // このクラスの属性定義を監査します。
36}
37
38/**
39 * クラスに適用された属性を監査し、`ReflectionAttribute::isRepeated()` を使用して
40 * その属性が定義上、繰り返し可能としてマークされているかを確認します。
41 *
42 * この関数は、`isRepeated()` の結果が期待される状態と異なる場合に、
43 * 「設定上の問題」または「潜在的なエラー」（キーワード「php iserror」に関連する状況）
44 * として報告する例を示します。
45 *
46 * @param string $className 監査対象のクラスの完全修飾名
47 */
48function auditAttributeDefinitions(string $className): void
49{
50    echo "--- クラス '{$className}' の属性定義監査 --- \n";
51    echo "  (ReflectionAttribute::isRepeated() メソッドの利用)\n\n";
52
53    try {
54        $reflectionClass = new ReflectionClass($className);
55
56        foreach ($reflectionClass->getAttributes() as $reflectionAttribute) {
57            $attributeName = $reflectionAttribute->getName();
58            // 属性のコンストラクタ引数にアクセスするため、インスタンスを作成します。
59            $attributeInstance = $reflectionAttribute->newInstance();
60
61            echo "  属性名: {$attributeName}\n";
62            echo "    適用時の引数: " . var_export($reflectionAttribute->getArguments(), true) . "\n";
63
64            // ReflectionAttribute::isRepeated() を呼び出し、
65            // この属性が定義上「Attribute::IS_REPEATABLE」としてマークされているかチェックします。
66            if ($reflectionAttribute->isRepeated()) {
67                echo "    -> 定義上「繰り返し可能」としてマークされています。\n";
68                // 「php iserror」関連付けの例:
69                // SingleConfigAttribute は、ビジネスルール上はクラスに一度しか適用されるべきではない
70                // と仮定した場合、`IS_REPEATABLE` として定義されていること自体が「設定エラー」です。
71                if ($attributeName === SingleConfigAttribute::class) {
72                    echo "    [重大な問題]: 属性 '{$attributeName}' は本来単一であるべきですが、\n";
73                    echo "                  誤って『繰り返し可能』として定義されています。これは『設定エラー』の可能性を示します。\n";
74                }
75            } else {
76                echo "    -> 定義上「繰り返し不可」としてマークされています (デフォルトまたは明示的)。\n";
77                // 「php iserror」関連付けの例:
78                // LogEventAttribute は複数回適用されることが期待されると仮定した場合、
79                // `IS_REPEATABLE` が設定されていないことは「設定漏れ」となります。
80                if ($attributeName === LogEventAttribute::class) {
81                    echo "    [警告]: 属性 '{$attributeName}' は複数回適用されることが期待されますが、\n";
82                    echo "            『繰り返し不可』として定義されています。これは『設定漏れ』の可能性を示します。\n";
83                }
84            }
85            echo "\n";
86        }
87    } catch (ReflectionException $e) {
88        // リフレクション中に例外が発生した場合のハンドリング
89        echo "エラー: クラス '{$className}' のリフレクション中に問題が発生しました: {$e->getMessage()}\n";
90    }
91}
92
93// 定義したクラスに対して監査関数を実行します。
94auditAttributeDefinitions(SystemService::class);

PHP 8のReflectionAttribute::isRepeated()メソッドは、クラスなどに適用された「属性（Attribute）」の定義が複数回適用できる（リピータブル）ように設定されているかを確認します。このメソッドは引数なしで呼び出し、属性が繰り返し可能ならtrueを、そうでなければfalseをブール値で返します。

このメソッドは、属性の定義が設計意図と合致しているか検証する際に特に重要です。サンプルコードでは、ReflectionClassを通じて取得した属性情報に対しisRepeated()を使用し、その定義が正しいかチェックしています。例えば、本来一度しか適用すべきでないSingleConfigAttributeにおいてisRepeated()がtrueを返す場合、定義自体が誤って「繰り返し可能」と設定された「設定エラー」を示唆します。逆に、複数回適用が期待されるLogEventAttributeでisRepeated()がfalseを返す場合、「設定漏れ」の警告となります。このように、isRepeated()は属性定義の妥当性を検証し、「php iserror」のような潜在的な問題点の発見に役立ちます。

Copy
1<?php
2
3// 繰り返し可能なカスタム属性を定義します。
4// #[Attribute] の引数に Attribute::IS_REPEATABLE を指定すると、
5// この属性を同じ宣言ターゲット（クラス、メソッドなど）に複数回使用できるようになります。
6#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
7class MyRepeatableAttribute
8{
9    public function __construct(public string $instanceName) {}
10}
11
12// 繰り返し可能ではないカスタム属性を定義します。
13// Attribute::IS_REPEATABLE フラグがないため、この属性は同じ宣言ターゲットに1回しか使用できません。
14#[Attribute(Attribute::TARGET_CLASS)]
15class MyNonRepeatableAttribute
16{
17    public function __construct(public string $reason) {}
18}
19
20/**
21 * 属性のデモンストレーションに使用するクラスです。
22 *
23 * MyRepeatableAttribute は複数回付与されています。
24 * MyNonRepeatableAttribute は1回のみ付与されています。
25 * (繰り返し可能ではない属性を複数回付与すると、PHPのパースエラーが発生します)
26 */
27#[MyRepeatableAttribute("First Instance")]
28#[MyRepeatableAttribute("Second Instance")]
29#[MyNonRepeatableAttribute("この属性は繰り返し使用できません。")]
30class ExampleTargetClass
31{
32    // このクラスに属性が付与されています。
33}
34
35/**
36 * クラスに付与された属性の繰り返し可能性をデモンストレーションします。
37 *
38 * `ReflectionAttribute::isRepeated()` メソッドの動作と、
39 * 「php is deprecated」のキーワードに関連付けて、PHPの組み込み属性である
40 * `#[Deprecated]` との関連性も説明します。
41 */
42function demonstrateAttributeRepetition(): void
43{
44    // リフレクションAPIを使って ExampleTargetClass の情報を取得します。
45    $reflectionClass = new ReflectionClass(ExampleTargetClass::class);
46
47    echo "--- 属性の繰り返し可能性のデモンストレーション ---\n\n";
48
49    // クラスに付与されている全ての属性を取得します。
50    $attributes = $reflectionClass->getAttributes();
51
52    if (empty($attributes)) {
53        echo "エラー: ExampleTargetClass に属性が見つかりませんでした。\n";
54        return;
55    }
56
57    foreach ($attributes as $reflectionAttribute) {
58        $attributeName = $reflectionAttribute->getName();
59        // ReflectionAttribute::isRepeated() は、この属性の定義が繰り返し可能である場合に true を返します。
60        $isRepeatable = $reflectionAttribute->isRepeated();
61
62        echo sprintf(
63            "属性 '%s': isRepeated() => %s\n",
64            $attributeName,
65            $isRepeatable ? 'true' : 'false'
66        );
67
68        if ($isRepeatable) {
69            echo "  説明: この属性は繰り返し可能です。同じ要素に複数回宣言することができます。\n";
70        } else {
71            echo "  説明: この属性は繰り返し可能ではありません。同じ要素には1回しか宣言できません。\n";
72        }
73
74        // キーワード「php is deprecated」に関連付けて補足説明を追加します。
75        if ($attributeName === MyNonRepeatableAttribute::class) {
76            echo "  補足: PHPの組み込み属性である `#[Deprecated]` も、この `MyNonRepeatableAttribute` と同様に\n";
77            echo "        繰り返し可能ではありません。そのため、同じ要素に複数回 `#[Deprecated]` を付与することはできません。\n";
78            echo "        `#[Deprecated]` は、非推奨になったコード要素を示すために使用されます。\n";
79        }
80        echo "\n";
81    }
82
83    echo "--- デモンストレーション終了 ---\n";
84}
85
86// デモンストレーション関数を実行します。
87demonstrateAttributeRepetition();
88

ReflectionAttribute::isRepeated() メソッドは、PHP 8で導入された属性（アトリビュート）が、同じ宣言ターゲット（クラス、メソッド、プロパティなど）に複数回適用できる「繰り返し可能な属性」であるかどうかを判定する際に使用します。このメソッドは引数を受け取りません。

戻り値は bool 型で、もし属性が繰り返し可能として定義されていれば true を、繰り返し不可能であれば false を返します。サンプルコードでは、#[Attribute(Attribute::IS_REPEATABLE)] を指定して定義された MyRepeatableAttribute は繰り返し可能であり、isRepeated() は true を返します。一方、Attribute::IS_REPEATABLE フラグがない MyNonRepeatableAttribute は繰り返し不可能であり、isRepeated() は false を返します。

この機能を使うと、プログラム実行時にリフレクションAPIを通じて属性の特性を動的に確認できます。なお、PHPの組み込み属性である #[Deprecated] も繰り返し可能ではありません。そのため、非推奨となったコード要素に #[Deprecated] を複数回付与することはできず、isRepeated() を確認した場合も false となります。#[Deprecated] は、将来的に削除される予定のコードを示すために利用されます。