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

Copy
1<?php
2
3/**
4 * DOMEntityのattributesプロパティの使用例を示します。
5 *
6 * このプロパティは、DTD（文書型定義）で定義されたエンティティに
7 * 関連付けられた属性のリストを取得するために使用されます。
8 * ただし、PHPのDOM実装では、このプロパティは常にnullを返します。
9 *
10 * このサンプルでは、DTD内で定義されたエンティティを取得し、
11 * そのattributesプロパティがnullであることを確認します。
12 */
13function showDomEntityAttributesExample(): void
14{
15    // DTDを含むXML文字列を定義します。
16    // 'logo'という名前の外部非解析エンティティを宣言しています。
17    $xmlString = <<<XML
18<?xml version="1.0" encoding="utf-8"?>
19<!DOCTYPE document [
20    <!ENTITY logo SYSTEM "php-logo.png" NDATA png>
21    <!NOTATION png SYSTEM "PNG Viewer">
22]>
23<document>
24    <image>&logo;</image>
25</document>
26XML;
27
28    // DOMDocumentオブジェクトを作成します。
29    $doc = new DOMDocument();
30
31    // XML文字列を読み込みます。
32    $doc->loadXML($xmlString);
33
34    // DocumentTypeノード（DTD）を取得します。
35    $doctype = $doc->doctype;
36
37    if ($doctype) {
38        // DocumentTypeからエンティティのリスト（DOMNamedNodeMap）を取得します。
39        $entities = $doctype->entities;
40
41        // 'logo'という名前のエンティティ（DOMEntityオブジェクト）を取得します。
42        // @see https://www.php.net/manual/ja/class.domentity.php
43        $entity = $entities->getNamedItem('logo');
44
45        if ($entity instanceof DOMEntity) {
46            echo "エンティティ名: " . $entity->nodeName . PHP_EOL;
47
48            // DOMEntityのattributesプロパティにアクセスします。
49            // 戻り値はDOMNamedNodeMapまたはnullですが、PHPでは常にnullが返されます。
50            // @see https://www.php.net/manual/ja/class.domentity.php#domentity.props.attributes
51            $attributes = $entity->attributes;
52
53            echo "attributesプロパティの値の型と値: ";
54            var_dump($attributes); // 出力: NULL
55        }
56    } else {
57        echo 'DTDが見つかりませんでした。' . PHP_EOL;
58    }
59}
60
61// 関数を実行して結果を表示します。
62showDomEntityAttributesExample();
63

このPHPコードは、DOMEntityクラスが持つattributesプロパティの使用例を示しています。このプロパティは、XMLのDTD（文書型定義）内で定義されたエンティティに関連付けられた属性のリストを取得するためのものです。

サンプルコードでは、まず<!ENTITY>タグを含むXML文字列を用意し、logoという名前のエンティティを定義しています。次に、DOMDocumentオブジェクトを使ってこのXMLを読み込み、DTDの中からlogoエンティティを表すDOMEntityオブジェクトを取得します。

続いて、取得したDOMEntityオブジェクトのattributesプロパティにアクセスします。このプロパティの戻り値は、属性の集まりであるDOMNamedNodeMapオブジェクト、またはnullです。しかし、PHPのDOM実装では、このプロパティは常にnullを返す仕様になっています。

そのため、最後にvar_dump関数でプロパティの値を画面に出力すると、NULLと表示されます。このコードは、DOMEntityのattributesプロパティが現在のPHPでは常にnullを返すという挙動を具体的に確認するためのものです。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * PHP 8で導入された「アトリビュート」を定義します。
7 * クラス、メソッド、プロパティ等に付与できるメタデータです。
8 * これ自体もクラスとして実装する必要があります。
9 */
10#[Attribute(Attribute::TARGET_METHOD)]
11final class Route
12{
13    public function __construct(
14        public string $path
15    ) {
16    }
17}
18
19/**
20 * アトリビュートと、旧来のアノテーション（PHPDocコメント）を比較するためのクラスです。
21 */
22final class MyController
23{
24    // --- PHP 8 Attributes ---
25    // #[Route('/api/v2/users')] のように、メタデータをコード構造の一部として記述します。
26    // これがPHP 8の「アトリビュート」です。言語機能として構文解析されます。
27    #[Route('/api/v2/users')]
28    public function getUsersByAttribute(): void
29    {
30        // APIの処理...
31    }
32
33    // --- PHPDoc Annotations ---
34    /**
35     * PHPDocコメント内にメタ情報を記述します。
36     * これが「アノテーション」と呼ばれる従来の方法です。
37     * これは単なるコメントであり、PHP自体は意味を解釈しません。
38     * @Route("/api/v1/users")
39     */
40    public function getUsersByAnnotation(): void
41    {
42        // 昔のAPIの処理...
43    }
44}
45
46
47/**
48 * リフレクションAPIを使って、メタデータを読み取り、比較するデモ関数です。
49 */
50function demonstrateAttributesVsAnnotations(): void
51{
52    try {
53        $reflection = new ReflectionClass(MyController::class);
54        $methods = $reflection->getMethods(ReflectionMethod::IS_PUBLIC);
55
56        echo "MyControllerクラスのメソッドからルート情報を読み取ります。" . PHP_EOL;
57        echo "--------------------------------------------------" . PHP_EOL;
58
59        foreach ($methods as $method) {
60            // PHP 8のアトリビュートを読み取る (構造化された方法)
61            $attributes = $method->getAttributes(Route::class);
62            if (!empty($attributes)) {
63                $routeInstance = $attributes[0]->newInstance();
64                echo "[Attribute] メソッド '{$method->getName()}' のパス: " . $routeInstance->path . PHP_EOL;
65                continue;
66            }
67
68            // 従来のアノテーションを読み取る (コメントを文字列としてパースする方法)
69            $docComment = $method->getDocComment();
70            if ($docComment && preg_match('/@Route\("(.+?)"\)/', $docComment, $matches)) {
71                echo "[Annotation] メソッド '{$method->getName()}' のパス: " . $matches[1] . PHP_EOL;
72            }
73        }
74    } catch (ReflectionException $e) {
75        echo "リフレクションエラー: " . $e->getMessage() . PHP_EOL;
76    }
77}
78
79// デモ関数を実行します。
80demonstrateAttributesVsAnnotations();
81

このPHPコードは、PHP 8で導入された「アトリビュート」と、従来から使われている「アノテーション」との違いを具体的に示しています。

MyControllerクラスのgetUsersByAttributeメソッドに付与されている#[Route(...)]がアトリビュートです。これはPHPの言語機能として正式にサポートされており、コードの構造の一部として解釈されます。デモ関数で使われているリフレクションAPIのgetAttributes()メソッドは、引数にアトリビュートのクラス名を受け取り、そのメタ情報を構造化されたオブジェクトの配列として返します。これにより、型安全で簡単に情報を扱うことができます。

一方、getUsersByAnnotationメソッドの上にある/** @Route(...) */がアノテーションです。これはPHPDoc形式のコメントであり、PHPのコードとしては意味を持ちません。情報を利用するにはgetDocComment()メソッドでコメント全体を文字列として取得し、正規表現などを用いて手動で解析（パース）する必要があります。

このように、アトリビュートは構文チェックが可能なモダンで堅牢なメタデータの記述方法であり、アノテーションは文字列解析に依存する従来の方法です。このサンプルコードは両者の読み取り方の違いを明確に比較しています。