【PHP8.x】attributesプロパティの使い方

Copy
1<?php
2
3/**
4 * PHP 8 Attributes (introduced in PHP 8.0) provide a structured,
5 * language-native way to add metadata to classes, methods, properties,
6 * functions, and parameters. This is a modern alternative to the older
7 * "annotations" which were typically parsed from docblock comments.
8 *
9 * This example demonstrates:
10 * 1. How to define a custom PHP 8 Attribute.
11 * 2. How to apply this Attribute, alongside a legacy "annotation" in a docblock.
12 * 3. How to programmatically read both PHP 8 Attributes and legacy annotations
13 *    using PHP's Reflection API, highlighting their fundamental difference.
14 */
15
16// 1. Define a custom PHP 8 Attribute
17// The `#[Attribute]` attribute itself is a built-in PHP attribute
18// that marks a class as an attribute class.
19// `Attribute::TARGET_PROPERTY | Attribute::TARGET_METHOD` specifies where this attribute can be applied.
20#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
21class MyMetadata
22{
23    // Attributes can have constructor parameters, making them strongly typed.
24    public function __construct(public string $description)
25    {
26    }
27}
28
29// 2. Define a class that uses both PHP 8 Attributes and legacy docblock annotations
30class MyService
31{
32    /**
33     * @legacyAnnotation "This is a comment-based annotation for a property."
34     */
35    #[MyMetadata("This is a native PHP 8 attribute for a property.")]
36    public string $config = 'default_value';
37
38    /**
39     * This is a standard docblock comment for a method.
40     * @legacyAnnotation "This is a comment-based annotation for a method."
41     * @param string $input A sample input parameter.
42     * @return string A processed string.
43     */
44    #[MyMetadata("This is a native PHP 8 attribute for a method.")]
45    public function processData(string $input): string
46    {
47        return strtoupper($input);
48    }
49}
50
51// 3. A class to read and demonstrate the difference between Attributes and Annotations
52class MetadataReader
53{
54    public function demonstrateReadingMetadata(object $object): void
55    {
56        $reflectionClass = new ReflectionClass($object);
57
58        echo "--- Analyzing Class: " . $reflectionClass->getName() . " ---\n\n";
59
60        // Read metadata from properties
61        foreach ($reflectionClass->getProperties() as $property) {
62            echo "Property: $" . $property->getName() . "\n";
63
64            // Reading PHP 8 Attributes: They are objects directly accessible via Reflection.
65            $attributes = $property->getAttributes(MyMetadata::class);
66            if (!empty($attributes)) {
67                echo "  PHP 8 Attributes found:\n";
68                foreach ($attributes as $attribute) {
69                    $instance = $attribute->newInstance(); // Get an instance of the attribute class
70                    echo "    - " . $attribute->getName() . ": " . $instance->description . "\n";
71                }
72            } else {
73                echo "  No PHP 8 Attributes found.\n";
74            }
75
76            // Reading legacy annotations: They are raw strings within the docblock
77            // and require manual parsing (e.g., with regex).
78            $docComment = $property->getDocComment();
79            if ($docComment !== false) {
80                echo "  Legacy Annotations (from DocBlock) found:\n";
81                // A simple regex to extract a specific legacy annotation
82                if (preg_match('/@legacyAnnotation "([^"]+)"/', $docComment, $matches)) {
83                    echo "    - legacyAnnotation: " . $matches[1] . "\n";
84                } else {
85                    echo "    - (No specific @legacyAnnotation found in docblock for this property.)\n";
86                }
87            } else {
88                echo "  No DocBlock comments (and thus no legacy annotations) found.\n";
89            }
90            echo "\n";
91        }
92
93        // Read metadata from methods
94        foreach ($reflectionClass->getMethods() as $method) {
95            echo "Method: " . $method->getName() . "()\n";
96
97            // Reading PHP 8 Attributes
98            $attributes = $method->getAttributes(MyMetadata::class);
99            if (!empty($attributes)) {
100                echo "  PHP 8 Attributes found:\n";
101                foreach ($attributes as $attribute) {
102                    $instance = $attribute->newInstance();
103                    echo "    - " . $attribute->getName() . ": " . $instance->description . "\n";
104                }
105            } else {
106                echo "  No PHP 8 Attributes found.\n";
107            }
108
109            // Reading legacy annotations
110            $docComment = $method->getDocComment();
111            if ($docComment !== false) {
112                echo "  Legacy Annotations (from DocBlock) found:\n";
113                if (preg_match('/@legacyAnnotation "([^"]+)"/', $docComment, $matches)) {
114                    echo "    - legacyAnnotation: " . $matches[1] . "\n";
115                } else {
116                    echo "    - (No specific @legacyAnnotation found in docblock for this method.)\n";
117                }
118            } else {
119                echo "  No DocBlock comments (and thus no legacy annotations) found.\n";
120            }
121            echo "\n";
122        }
123    }
124}
125
126// Instantiate the service and the reader, then run the demonstration.
127$service = new MyService();
128$reader = new MetadataReader();
129$reader->demonstrateReadingMetadata($service);
130
131?>

PHPのこのサンプルコードは、PHP 8で導入された「Attributes（属性）」の利用方法と、それ以前に用いられていた「アノテーション」との違いを解説しています。Attributesは、#[属性名(引数)]という構文で、クラス、メソッド、プロパティなどに構造化されたメタデータを直接付与する、言語ネイティブな機能です。これは、DocBlockコメント内に記述され、プログラムで利用する際に文字列解析が必要だった従来のアノテーションとは根本的に異なります。

コードでは、まずMyMetadataというカスタムAttributeを定義し、これをクラスのプロパティやメソッドに適用する例を示しています。次に、MetadataReaderクラスがPHPのReflection APIを用いて、これらのメタデータを読み取る過程を説明しています。AttributesはReflectionを通じて直接オブジェクトとして取得でき、そのプロパティにアクセスすることで定義された情報を取り出すことができます。一方で、アノテーションはDocBlockコメントの生文字列から正規表現などを使って手動で解析する必要があることを示しており、両者の明確な違いを理解できます。これにより、Attributesはメタデータ管理をより堅牢かつ効率的に行えるようになります。