【PHP8.x】DOMEntityReference::previousSiblingプロパティの使い方

Copy
1<?php
2
3/**
4 * Demonstrates the use of DOMEntityReference::previousSibling property in PHP 8.
5 *
6 * This function loads an XML string into a DOMDocument, explicitly preventing
7 * entity expansion to ensure DOMEntityReference nodes are present. It then
8 * locates such a node and displays information about its immediately preceding
9 * sibling node in the DOM tree. This is useful for understanding DOM tree
10 * traversal, especially when dealing with XML entities.
11 *
12 * @return void
13 */
14function demonstrateDomEntityReferencePreviousSibling(): void
15{
16    $dom = new DOMDocument();
17
18    // Define an XML string.
19    // The XML is structured to place '<firstElement>' immediately before
20    // the entity reference without any intervening whitespace text nodes.
21    // LIBXML_NOENT is crucial here: it prevents the expansion of entity
22    // references, ensuring that '&example;' exists as a DOMEntityReference
23    // node in the DOM tree, rather than being replaced by its content.
24    $xml = <<<XML
25<?xml version="1.0"?>
26<!DOCTYPE root [
27  <!ENTITY example "This is an example entity.">
28]>
29<root><firstElement>First content</firstElement>&example;<secondElement>Second content</secondElement></root>
30XML;
31
32    // Load the XML string into the DOMDocument, preserving entity references.
33    $dom->loadXML($xml, LIBXML_NOENT);
34
35    echo "--- Demonstrating DOMEntityReference::previousSibling ---\n\n";
36
37    $root = $dom->documentElement;
38    $entityReferenceNode = null;
39
40    // Iterate through the child nodes of the root element to find the
41    // DOMEntityReference node.
42    foreach ($root->childNodes as $childNode) {
43        if ($childNode instanceof DOMEntityReference) {
44            $entityReferenceNode = $childNode;
45            break; // Found the entity reference node.
46        }
47    }
48
49    if ($entityReferenceNode) {
50        echo "Found DOMEntityReference node:\n";
51        echo "  Node Name: '" . $entityReferenceNode->nodeName . "'\n"; // e.g., 'example' for &example;
52        // DOM_ENTITY_REFERENCE_NODE is a PHP constant representing the node type for entity references.
53        echo "  Node Type: " . $entityReferenceNode->nodeType . " (DOM_ENTITY_REFERENCE_NODE)\n";
54        // The nodeValue property of a DOMEntityReference is always an empty string.
55        echo "  Node Value: '" . $entityReferenceNode->nodeValue . "' (always empty for entity references)\n";
56
57        // Access the `previousSibling` property to get the node immediately preceding it.
58        $previousSibling = $entityReferenceNode->previousSibling;
59
60        if ($previousSibling) {
61            echo "\nInformation about the previousSibling node:\n";
62            echo "  Node Name: '" . $previousSibling->nodeName . "'\n";
63            echo "  Node Type: " . $previousSibling->nodeType . "\n";
64            // Trim nodeValue for clean output, especially for text nodes.
65            echo "  Node Value: '" . trim($previousSibling->nodeValue) . "'\n";
66            echo "  Is a DOMElement? " . ($previousSibling instanceof DOMElement ? "Yes" : "No") . "\n";
67
68            // For this specific example, the previous sibling should be the 'firstElement'.
69            if ($previousSibling instanceof DOMElement && $previousSibling->nodeName === 'firstElement') {
70                echo "  Confirmed: This is the '<firstElement>' node as expected.\n";
71            }
72        } else {
73            echo "\nNo previous sibling found for the DOMEntityReference node.\n";
74        }
75    } else {
76        echo "Error: Could not find a DOMEntityReference node in the document.\n";
77        echo "This typically means entities were expanded (LIBXML_NOENT not used or entity declaration missing).\n";
78    }
79}
80
81// Execute the demonstration function.
82demonstrateDomEntityReferencePreviousSibling();

DOMEntityReference::previousSiblingプロパティは、XMLドキュメント内でエンティティ参照ノードの直前にある兄弟ノードを取得するために使用されます。このプロパティは引数を取らず、戻り値としてDOMNodeオブジェクト、または直前の兄弟ノードが存在しない場合はnullを返します。

このサンプルコードでは、まずXMLエンティティ定義を含むXML文字列を準備しています。特に重要なのは、DOMDocument::loadXML()メソッドにLIBXML_NOENTフラグを渡している点です。これにより、&example;のようなXMLエンティティがその内容に展開されず、DOMEntityReferenceノードとしてDOMツリー内に保持されます。

コードは、読み込まれたDOMツリーの中からDOMEntityReference型のノードを特定します。&example;エンティティ参照ノードが見つかると、そのpreviousSiblingプロパティにアクセスし、DOMツリー上でこのエンティティ参照の直前に位置する兄弟ノードを取得します。今回のXML構造では、このプロパティにより<firstElement>要素が取得されます。その後、取得した兄弟ノードのノード名、タイプ、値などの情報が表示され、それが期待される<firstElement>ノードであることを確認しています。このプロパティは、DOMツリーの特定のノードから前方向へ辿る際に役立ちます。

Copy
1<?php
2
3/**
4 * DOMEntityReference::previousSibling プロパティの動作をデモンストレーションします。
5 *
6 * DOMEntityReference は、XML ドキュメント内でエンティティ（例: &amp;）が参照されている場所を
7 * 表現するノードです。previousSibling プロパティは、このエンティティ参照ノードの
8 * 直前に位置する兄弟ノードを返します。
9 *
10 * システムエンジニアを目指す初心者の方にも分かりやすいように、
11 * DOM ツリーを手動で構築して、その動作を明確に示します。
12 */
13function demonstrateDomEntityReferencePreviousSibling(): void
14{
15    // 1. DOMDocument オブジェクトを作成します。
16    //    XMLのバージョンとエンコーディングを指定します。
17    $dom = new DOMDocument('1.0', 'UTF-8');
18    // 出力時にXMLが読みやすいように整形するように設定します。
19    $dom->formatOutput = true;
20
21    // 2. ルート要素（最上位の要素）を作成し、ドキュメントに追加します。
22    $root = $dom->createElement('root');
23    $dom->appendChild($root);
24
25    // 3. 最初のテキストノードを作成し、ルート要素の子として追加します。
26    $textNode1 = $dom->createTextNode('これは最初のテキストです。');
27    $root->appendChild($textNode1);
28
29    // 4. DOMEntityReference オブジェクトを明示的に作成します。
30    //    ここでは、標準の '&amp;' (アンパサンド) エンティティを例として使用します。
31    //    'amp' という名前でエンティティ参照ノードを作成します。
32    $entityRef = $dom->createEntityReference('amp');
33    // 5. 作成したエンティティ参照ノードを、最初のテキストノードの後に続けて追加します。
34    $root->appendChild($entityRef);
35
36    // 6. 2番目のテキストノードを作成し、エンティティ参照ノードの後に続けて追加します。
37    $textNode2 = $dom->createTextNode('これはエンティティの後のテキストです。');
38    $root->appendChild($textNode2);
39
40    echo "--- 構築されたDOMツリーのXML表現 --- \n";
41    // 現在構築されたDOMツリーのXML表現を出力します。
42    // 注: createEntityReference で作成したエンティティは、
43    //     saveXML() で出力される際にエンティティ参照としてではなく、
44    //     展開されたテキストとして表示される場合があります。
45    //     しかし、DOM内部ではDOMEntityReferenceオブジェクトは独立したノードとして存在しています。
46    echo $dom->saveXML();
47    echo "\n";
48
49    echo "--- DOMEntityReference の previousSibling を確認 --- \n";
50
51    // 7. 作成した $entityRef (DOMEntityReference オブジェクト) の
52    //    previousSibling プロパティにアクセスし、直前の兄弟ノードを取得します。
53    //    この例では、$entityRef の直前の兄弟ノードは $textNode1 (最初のテキストノード) です。
54    $previousSibling = $entityRef->previousSibling;
55
56    if ($previousSibling) {
57        echo "DOMEntityReference の previousSibling が見つかりました。\n";
58        echo "  ノードタイプ: " . getNodeTypeName($previousSibling->nodeType) . "\n";
59        echo "  ノード名: '" . $previousSibling->nodeName . "'\n"; // テキストノードの場合、ノード名は #text となります。
60        echo "  ノード値: '" . $previousSibling->nodeValue . "'\n";
61        // 期待される出力:
62        // ノードタイプ: XML_TEXT_NODE (テキストノード)
63        // ノード名: '#text'
64        // ノード値: 'これは最初のテキストです。'
65    } else {
66        echo "DOMEntityReference の previousSibling は見つかりませんでした。\n";
67        echo "これは、エンティティ参照ノードが親ノードの最初の子である場合に発生します。\n";
68    }
69
70    echo "\n--- previousSibling が存在しない場合の例 --- \n";
71    // エンティティ参照が親ノードの最初の子である場合の例を示します。
72    $dom2 = new DOMDocument('1.0', 'UTF-8');
73    $root2 = $dom2->createElement('root2');
74    $dom2->appendChild($root2);
75    $entityRef2 = $dom2->createEntityReference('lt'); // '&lt;' を表現するエンティティ参照ノード
76    $root2->appendChild($entityRef2); // エンティティ参照ノードを最初の子として追加
77    $textNode3 = $dom2->createTextNode('これは続くテキストです。');
78    $root2->appendChild($textNode3);
79
80    echo "別のDOMツリー:\n";
81    echo $dom2->saveXML();
82    echo "\n";
83
84    $previousSibling2 = $entityRef2->previousSibling;
85    if ($previousSibling2) {
86        echo "entityRef2 の previousSibling が見つかりました。(これは通常予期しない動作です。)\n";
87    } else {
88        echo "entityRef2 の previousSibling は見つかりませんでした。\n";
89        echo "(期待通り、entityRef2 は親ノード 'root2' の最初の子ノードであるためです。)\n";
90    }
91}
92
93/**
94 * PHPのXML_NODE_TYPE定数に対応する、より人間が理解しやすいノードタイプ名を返します。
95 *
96 * @param int $nodeType ノードタイプID (例: XML_ELEMENT_NODE)
97 * @return string ノードタイプ名とその説明
98 */
99function getNodeTypeName(int $nodeType): string
100{
101    return match ($nodeType) {
102        XML_ELEMENT_NODE => 'XML_ELEMENT_NODE (要素ノード)',
103        XML_ATTRIBUTE_NODE => 'XML_ATTRIBUTE_NODE (属性ノード)',
104        XML_TEXT_NODE => 'XML_TEXT_NODE (テキストノード)',
105        XML_CDATA_SECTION_NODE => 'XML_CDATA_SECTION_NODE (CDATAセクションノード)',
106        XML_ENTITY_REF_NODE => 'XML_ENTITY_REF_NODE (エンティティ参照ノード)',
107        XML_ENTITY_NODE => 'XML_ENTITY_NODE (エンティティ宣言ノード)',
108        XML_PI_NODE => 'XML_PI_NODE (処理命令ノード)',
109        XML_COMMENT_NODE => 'XML_COMMENT_NODE (コメントノード)',
110        XML_DOCUMENT_NODE => 'XML_DOCUMENT_NODE (ドキュメントノード)',
111        XML_DOCUMENT_TYPE_NODE => 'XML_DOCUMENT_TYPE_NODE (ドキュメントタイプノード)',
112        XML_DOCUMENT_FRAG_NODE => 'XML_DOCUMENT_FRAG_NODE (ドキュメントフラグメントノード)',
113        XML_NOTATION_NODE => 'XML_NOTATION_NODE (記法ノード)',
114        XML_HTML_DOCUMENT_NODE => 'XML_HTML_DOCUMENT_NODE (HTMLドキュメントノード)',
115        default => 'UNKNOWN_NODE_TYPE (不明なノードタイプ)',
116    };
117}
118
119// サンプルコードのメイン関数を実行します。
120demonstrateDomEntityReferencePreviousSibling();

PHPのDOMEntityReference::previousSiblingプロパティは、XMLドキュメントの構造をプログラムで操作する際に利用されます。DOMEntityReferenceクラスは、XMLドキュメント内で&（アンパサンド）のようなエンティティ参照が使われている箇所を表現するノードです。

このpreviousSiblingプロパティは、特定のDOMEntityReferenceノードの「直前に位置する兄弟ノード」を取得するために使用されます。兄弟ノードとは、同じ親ノードを持つ、隣り合ったノードのことを指します。

このプロパティに引数はなく、戻り値として?DOMNode型を返します。これは、もし直前の兄弟ノードが存在すればそのDOMNodeオブジェクトが返され、存在しない場合（例えば、対象のエンティティ参照ノードが親ノードの最初の子である場合など）はnullが返されることを意味します。

サンプルコードでは、XMLドキュメントのルート要素の下に「最初のテキストノード」、&を表す「エンティティ参照ノード」、そして「2番目のテキストノード」をこの順序で追加しています。この構成において、エンティティ参照ノードのpreviousSiblingプロパティにアクセスすると、直前の「最初のテキストノード」が取得される様子が示されており、ノード間の順序関係をプログラムで確認できることを表しています。