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

Copy
1<?php
2
3/**
4 * DOMEntity::notationName プロパティの使用方法をデモンストレーションします。
5 *
6 * このプロパティは、DOMEntityが参照する記法（notation）の名前を返します。
7 * 例えば、外部の非XMLデータを参照するエンティティがどの形式であるかを示す場合に使用されます。
8 *
9 * @return void
10 */
11function demonstrateDomEntityNotationName(): void
12{
13    // 記法（notation）と、その記法を参照するエンティティを定義するXMLを作成します。
14    // ここでは 'gif_type' という記法と、それを参照する 'mylogo' というエンティティを定義しています。
15    $xml = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<!DOCTYPE document [
18  <!NOTATION gif_type SYSTEM "image/gif">
19  <!ENTITY mylogo SYSTEM "path/to/logo.gif" NDATA gif_type>
20]>
21<document>
22  <item>Example entity reference: &mylogo;</item>
23</document>
24XML;
25
26    $dom = new DOMDocument();
27    // XML文字列をロードします。DOMDocumentはDTDも解析します。
28    $dom->loadXML($xml);
29
30    // ドキュメントタイプノード（DTD）を取得します。
31    $doctype = $dom->doctype;
32
33    if ($doctype && $doctype->entities) {
34        echo "DOMDocumentに宣言されたエンティティを検索しています...\n";
35
36        // 宣言されたすべてのエンティティを反復処理します。
37        foreach ($doctype->entities as $entity) {
38            // ノードがDOMEntityのインスタンスであることを確認します。
39            if ($entity instanceof DOMEntity) {
40                // DOMEntity::notationName プロパティにアクセスし、記法の名前を取得します。
41                // 記法が指定されていない場合、nullが返されます。
42                $notationName = $entity->notationName;
43
44                echo "エンティティ名: " . $entity->nodeName;
45                if ($notationName !== null) {
46                    echo ", 記法名 (notationName): " . $notationName . "\n";
47                } else {
48                    echo ", 記法名 (notationName): (未指定またはnull)\n";
49                }
50            }
51        }
52    } else {
53        echo "XMLドキュメントにDTDまたはエンティティが見つかりませんでした。\n";
54    }
55}
56
57// デモンストレーション関数を実行します。
58demonstrateDomEntityNotationName();

PHP 8のDOMEntity::notationNameプロパティは、XMLドキュメント内のエンティティが参照する記法（Notation）の名前を取得します。引数はありません。記法の名前を文字列で返すか、記法が未指定の場合はnullを返します。

サンプルコードでは、<!NOTATION>と<!ENTITY ... NDATA>宣言を持つXMLで、外部ファイルを参照するエンティティを定義しています。「gif_type」記法が「image/gif」形式を示し、「mylogo」エンティティがこの記法を参照しています。

DOMDocumentでXMLをロード後、$dom->doctype->entitiesから宣言済みエンティティを取得して処理します。DOMEntityのインスタンスであるエンティティから$entity->notationNameプロパティで記法の名前を取得し、出力しています。これにより、「mylogo」エンティティの記法名「gif_type」が取得され、XML内の外部データ形式をプログラムで確認できます。

Copy
1<?php
2
3/**
4 * DOMEntityクラスのnotationNameプロパティの使用例を示します。
5 *
6 * notationNameプロパティは、エンティティが外部エンティティであり、
7 * そのエンティティ宣言に表記名（notation name）が含まれている場合に、その表記名を返します。
8 * 内部エンティティの場合や、外部エンティティでも表記名が指定されていない場合はnullを返します。
9 */
10function demonstrateDomEntityNotationName(): void
11{
12    // XMLドキュメントを定義します。
13    // ここには、様々なタイプのエンティティ（DTDで定義）が含まれています。
14    // NDATAキーワードを使って、外部エンティティに表記名を指定しています。
15    $xmlString = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<!DOCTYPE root [
18  <!-- 内部エンティティ: 表記名はありません -->
19  <!ENTITY internal_entity "これは内部エンティティです。">
20
21  <!-- 外部エンティティ: SYSTEM識別子がありますが、NDATAキーワードで表記名が指定されていません -->
22  <!ENTITY external_entity SYSTEM "http://example.com/some_data.txt">
23
24  <!-- 表記名定義: これはXMLの妥当性検証に必要ですが、notationNameプロパティの値には直接影響しません。-->
25  <!NOTATION gif SYSTEM "image/gif">
26  <!NOTATION png SYSTEM "image/png">
27
28  <!-- 外部エンティティ: NDATAキーワードで「png」という表記名が指定されています -->
29  <!ENTITY logo SYSTEM "http://example.com/logo.png" NDATA png>
30
31  <!-- 外部エンティティ: NDATAキーワードで「pdf_app」という表記名が指定されています。
32       この「pdf_app」はDTD内でNOTATIONとして定義されていませんが、notationNameプロパティは返されます。 -->
33  <!ENTITY manual SYSTEM "http://example.com/manual.pdf" NDATA pdf_app>
34]>
35<root>
36  <description>エンティティの使用例</description>
37  <content>&internal_entity;</content>
38  <logo_ref>&logo;</logo_ref>
39  <manual_ref>&manual;</manual_ref>
40</root>
41XML;
42
43    $dom = new DOMDocument();
44    // 外部DTDやエンティティ実体を解決するかどうかを設定します。
45    // このサンプルではnotationNameプロパティの値の取得が目的のため必須ではありませんが、
46    // 外部リソースを含むXMLを扱う際にはtrueにすることが一般的です。
47    $dom->resolveExternals = true;
48    // XMLをロードします。
49    if (!$dom->loadXML($xmlString)) {
50        echo "エラー: XMLのロードに失敗しました。XML文字列を確認してください。\n";
51        return;
52    }
53
54    // ドキュメントタイプノード（DTD）を取得します。
55    $doctype = $dom->doctype;
56
57    if (!$doctype) {
58        echo "エラー: XMLドキュメントにDOCTYPEが見つかりません。\n";
59        return;
60    }
61
62    // ドキュメントに定義されているエンティティのコレクションを取得します。
63    // これらのエンティティはDTD内で定義されています。
64    $entities = $doctype->entities;
65
66    if (!$entities->length) {
67        echo "警告: DTD内でエンティティが定義されていません。\n";
68        return;
69    }
70
71    echo "--- DOMEntity::notationName プロパティのデモンストレーション ---\n\n";
72
73    // 各エンティティをループし、その名称とnotationNameプロパティの値を出力します。
74    foreach ($entities as $entityName => $entityNode) {
75        // DOMEntityオブジェクトであることを確認
76        if ($entityNode instanceof DOMEntity) {
77            echo "エンティティ名: " . $entityNode->nodeName . "\n";
78            echo "  エンティティ値 (nodeValue): " . ($entityNode->nodeValue === null ? "null" : "'" . $entityNode->nodeValue . "'") . "\n";
79            // notationNameプロパティの値を取得。nullの場合は "N/A (null)" と表示
80            echo "  表記名 (notationName): " . ($entityNode->notationName ?? "N/A (null)") . "\n";
81            echo "--------------------------------------------------\n";
82        }
83    }
84
85    echo "\n[解説]\n";
86    echo "- 'internal_entity': 内部エンティティのため、notationNameプロパティは null を返します。\n";
87    echo "- 'external_entity': 外部エンティティですが、NDATAキーワードで表記名が指定されていないため、notationNameプロパティは null を返します。\n";
88    echo "- 'logo': 外部エンティティで 'NDATA png' が指定されているため、notationNameプロパティは 'png' を返します。\n";
89    echo "- 'manual': 外部エンティティで 'NDATA pdf_app' が指定されているため、notationNameプロパティは 'pdf_app' を返します。\n";
90    echo "  NDATAキーワードで指定された名前自体がnotationNameプロパティの値として返されます。\n";
91    echo "  その名前がDTDで別途NOTATIONとして定義されているかどうかは、notationNameプロパティの値には直接影響しません。\n";
92    echo "  (ただし、XMLが妥当であるためには、NDATAで指定された名前はDTD内でNOTATIONとして定義されている必要があります。)\n";
93}
94
95// デモンストレーション関数を実行します。
96demonstrateDomEntityNotationName();

PHPのDOMEntity::notationNameプロパティは、XMLドキュメントのDTD（Document Type Definition）で定義されるエンティティに関する情報を提供するものです。このプロパティは引数を取らず、エンティティの表記名を表す文字列、または表記名が存在しない場合はnullを返します。

具体的には、エンティティが外部ファイルなどを参照する「外部エンティティ」であり、その定義にNDATAキーワードを用いて「表記名（notation name）」が指定されている場合に、その表記名を文字列として取得できます。例えば、サンプルコードのlogoエンティティではNDATA pngと指定されているため、notationNameプロパティは"png"を返します。また、manualエンティティのNDATA pdf_appのように、DTD内でNOTATIONとして定義されていない名前が指定されていても、指定された名前自体が戻り値となります。

一方で、エンティティがXMLドキュメント内部で完結する「内部エンティティ」である場合や、外部エンティティであってもNDATAキーワードによる表記名が指定されていない場合は、notationNameプロパティはnullを返します。サンプルコードのinternal_entityやexternal_entityがこれらのケースに該当し、nullが返されていることが確認できます。

このプロパティを使用することで、XMLのエンティティがどのような外部データを指し示しているか、その表記名を通じて判断できるため、XMLの処理において特定の外部リソースを識別する際に役立ちます。戻り値の型はstringまたはnullです。