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

Copy
1<?php
2
3/**
4 * Demonstrates how to retrieve the notation name of a DOM entity.
5 *
6 * In PHP's DOM extension, `Dom\Entity::notationName` allows you to get
7 * the name of a notation associated with an XML entity, as defined in a DTD.
8 * This is particularly useful for handling external unparsed entities.
9 */
10function demonstrateDomEntityNotationName(): void
11{
12    // 1. Define an XML string with a Document Type Definition (DTD) that includes:
13    //    - A NOTATION declaration: defines a format for external data.
14    //    - An ENTITY declaration: references external unparsed data and associates it with a notation.
15    $xmlString = <<<XML
16<?xml version="1.0" encoding="UTF-8"?>
17<!DOCTYPE document [
18  <!-- Declares a notation named 'gif' for GIF image format. -->
19  <!NOTATION gif SYSTEM "image/gif">
20  <!-- Declares an external unparsed entity 'myImage' associated with the 'gif' notation. -->
21  <!ENTITY myImage SYSTEM "file.gif" NDATA gif>
22  <!-- Declares a general parsed entity 'myText' without a notation. -->
23  <!ENTITY myText "This is some sample text.">
24]>
25<document>
26  <description>Example XML showcasing DTD entities.</description>
27  <!-- Referencing entities in the document body. -->
28  <image>&myImage;</image>
29  <text>&myText;</text>
30</document>
31XML;
32
33    // 2. Create a new DOM Document instance.
34    $dom = new Dom\Document();
35
36    // 3. Load the XML string into the DOM Document.
37    //    LIBXML_DTDATTR ensures DTD attributes are processed correctly.
38    //    LIBXML_NOENT is often used for entity substitution, but here it helps ensure
39    //    the entities map is populated correctly for NDATA entities too.
40    $dom->loadXML($xmlString, LIBXML_DTDATTR | LIBXML_NOENT);
41
42    echo "--- Examining DOM Entities and their Notation Names ---\n";
43
44    // 4. Access the Document Type Definition (DTD) if it exists.
45    $doctype = $dom->doctype;
46
47    if ($doctype instanceof Dom\DocumentType) {
48        echo "Found DOCTYPE named: '" . $doctype->name . "'\n";
49        echo "Entities declared in this DOCTYPE:\n";
50
51        // 5. Iterate through the entities declared in the DTD.
52        //    The `Dom\DocumentType::entities` property holds a Dom\NamedNodeMap of Dom\Entity objects.
53        foreach ($doctype->entities as $entity) {
54            if ($entity instanceof Dom\Entity) {
55                $entityName = $entity->nodeName;     // The name of the entity (e.g., 'myImage', 'myText').
56                $notationName = $entity->notationName; // The name of the notation, if associated (e.g., 'gif').
57
58                echo "  - Entity: '$entityName'";
59                if ($notationName !== null) {
60                    echo ", Notation: '$notationName'"; // Output the notation name if present.
61                } else {
62                    echo ", Notation: (none)";       // Indicate no notation for this entity.
63                }
64                echo "\n";
65            }
66        }
67    } else {
68        echo "No DOCTYPE found in the XML document.\n";
69    }
70
71    echo "------------------------------------------------------\n";
72}
73
74// Execute the demonstration function.
75demonstrateDomEntityNotationName();

Dom\Entity::notationNameは、PHPのDOM拡張機能において、XMLのDTD（Document Type Definition）内で宣言されたエンティティに関連付けられた表記の名前を取得するためのプロパティです。このプロパティは引数を取らず、戻り値としてstring型またはnullを返します。特に、XMLパーサが内容を直接解釈せず、外部のアプリケーションに処理を委ねる「外部未解析エンティティ」が、どのような形式の外部データであるかを示す「表記（notation）」を持っている場合にその名前を取得できます。表記が関連付けられていないエンティティの場合にはnullが返されます。

サンプルコードでは、まずNOTATION宣言とENTITY ... NDATA宣言を含むXML文字列を定義しています。ここではgifという表記を定義し、myImageという外部未解析エンティティをこのgif表記に関連付けています。このXMLをDom\Documentにロードした後、$dom->doctype->entitiesプロパティを通じて、DTD内で宣言されたエンティティのコレクションにアクセスします。

コレクション内の各Dom\Entityオブジェクトについて、notationNameプロパティを参照しています。myImageエンティティでは、定義されたgifという表記名が正確に取得できることが示されます。一方、表記が関連付けられていないmyTextのような一般的なエンティティでは、notationNameはnullを返すことが確認できます。この機能は、XMLドキュメント内で参照される外部リソースのタイプをプログラム的に識別し、それに応じた処理を適用する際に役立ちます。

Copy
1<?php
2
3/**
4 * PHPのDom\Entity::notationName プロパティの使用例を示します。
5 * このプロパティは、XMLの非解析エンティティ (Unparsed Entity) に関連付けられた表記名 (Notation Name) を取得します。
6 * システムエンジニアを目指す初心者向けに、具体的なXML例を用いて動作を説明します。
7 */
8function demonstrateDomEntityNotationName(): void
9{
10    // XMLドキュメント文字列を定義します。
11    // ここでは、DTD (Document Type Definition) 内で2種類のエンティティを定義しています。
12    // 1. 'my_unparsed_entity': 'gif' という表記に関連付けられた非解析エンティティ。
13    //    非解析エンティティは、XMLパーサーによって内容が解析されない外部リソースを参照します。
14    // 2. 'my_parsed_entity': XMLパーサーによって内容が解析される通常のエンティティ。
15    $xmlString = <<<XML
16<!DOCTYPE doc [
17  <!NOTATION gif SYSTEM "image/gif">
18  <!ENTITY my_unparsed_entity SYSTEM "image.gif" NDATA gif>
19  <!ENTITY my_parsed_entity "これは解析済みエンティティです。">
20]>
21<doc>
22  <!-- XMLのコンテンツ自体は Dom\Entity プロパティの取得に直接影響しません。 -->
23  <example/>
24</doc>
25XML;
26
27    $dom = new DOMDocument();
28    // XMLロード時のエラー表示を抑制します。
29    // 実際のアプリケーションでは、エラーハンドリングを適切に行うべきです。
30    libxml_use_internal_errors(true);
31    if (!$dom->loadXML($xmlString)) {
32        echo "エラー: XMLのロードに失敗しました。\n";
33        libxml_clear_errors(); // エラー情報をクリア
34        return;
35    }
36    libxml_clear_errors(); // 成功した場合もエラー情報をクリア
37
38    // ドキュメントタイプ (DOCTYPE) ノードを取得します。
39    // XMLエンティティは通常、DOCTYPE内で定義されます。
40    $doctype = $dom->doctype;
41
42    if ($doctype === null) {
43        echo "XMLドキュメントにDOCTYPEが見つかりませんでした。\n";
44        return;
45    }
46
47    echo "DOCTYPEに定義されているエンティティの情報を表示します:\n\n";
48
49    // ドキュメントタイプからエンティティのコレクションを反復処理します。
50    // 各要素は Dom\Entity オブジェクトです。
51    foreach ($doctype->entities as $entity) {
52        echo "エンティティ名: " . $entity->nodeName . "\n";
53
54        // Dom\Entity::notationName プロパティにアクセスします。
55        // 戻り値は ?string (string または null)。
56        // - 非解析エンティティの場合: 関連付けられた表記名 (例: "gif") を返します。
57        // - 解析済みエンティティや表記がない場合: null を返します。
58        $notationName = $entity->notationName;
59
60        if ($notationName !== null) {
61            echo "  表記名 (Notation Name): '" . $notationName . "'\n";
62            echo "  このエンティティは非解析エンティティです。\n";
63            // 非解析エンティティは通常、外部リソースを参照するため System ID を持ちます。
64            echo "  System ID: " . ($entity->systemId ?? "N/A") . "\n";
65            if ($entity->publicId !== null) {
66                echo "  Public ID: " . $entity->publicId . "\n";
67            }
68        } else {
69            echo "  表記名 (Notation Name): null (解析済みエンティティまたは表記がありません)\n";
70            echo "  このエンティティは解析済みエンティティである可能性が高いです。\n";
71        }
72        echo "\n";
73    }
74}
75
76// 関数を実行し、Dom\Entity::notationName の動作を確認します。
77demonstrateDomEntityNotationName();

PHPのDom\Entity::notationNameプロパティは、XMLドキュメント内で定義されたエンティティに関する情報を提供するものです。このプロパティは、特に「非解析エンティティ (Unparsed Entity)」に関連付けられた「表記名 (Notation Name)」を取得するために使用されます。非解析エンティティとは、XMLパーサーがその内容を直接解析せず、代わりに外部リソースとして扱うエンティティのことを指します。通常、DTD（Document Type Definition）内でNDATAキーワードと共に定義され、その外部リソースの形式を示す表記名が関連付けられます。

notationNameプロパティは引数を取りません。戻り値は?string型であり、エンティティに表記名が関連付けられている場合はその表記名（文字列）を返します。例えば、画像ファイルへの参照など、特定の形式のリソースを示す場合に利用されます。一方で、通常の解析済みエンティティ（XMLパーサーによって内容が解析されるエンティティ）や、表記名が関連付けられていないエンティティの場合にはnullを返します。

サンプルコードでは、非解析エンティティ「my_unparsed_entity」と解析済みエンティティ「my_parsed_entity」を含むXMLを定義し、それぞれのエンティティに対してnotationNameプロパティの動作を確認しています。非解析エンティティ「my_unparsed_entity」からは「gif」という表記名が取得される一方、解析済みエンティティからはnullが返されることで、このプロパティの挙動を具体的に示しています。これにより、XML内で外部リソースの形式を識別する際に応用できることを理解できます。