【PHP8.x】DOMEntityReference::compareDocumentPosition()メソッドの使い方

Copy
1<?php
2
3/**
4 * このファイルは、DOMEntityReference::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * DOM (Document Object Model) のノード間におけるドキュメント内での位置関係を比較する方法を、
7 * システムエンジニアを目指す初心者にも分かりやすく解説します。
8 *
9 * PHPのDOM拡張機能は、XMLやHTMLドキュメントをオブジェクトとして操作するための機能を提供します。
10 * このサンプルでは、DOMEntityReference ノードをプログラムで作成し、
11 * その他のノードとの位置関係を比較します。
12 *
13 * `phpdocumentor`でドキュメントを生成する際に読み込まれるよう、
14 * PHPDoc形式でコメントを記述しています。
15 * `composer`で管理されるプロジェクトに含める場合も、
16 * 推奨コーディングスタイルに準拠しています。
17 *
18 * @package Demo
19 * @subpackage DOM
20 * @author Your Name <your.email@example.com>
21 * @license MIT license (例として)
22 * @link https://www.php.net/manual/ja/class.domentityreference.php
23 * @see DOMNode::compareDocumentPosition
24 * @version 1.0.0
25 */
26
27/**
28 * 2つのDOMノード間の位置関係を比較し、結果を分かりやすい文字列で返します。
29 *
30 * compareDocumentPosition メソッドは、指定された `$otherNode` が
31 * 呼び出し元の `$baseNode` に対してドキュメント内のどの位置にあるかを示すビットマスクを返します。
32 * 戻り値は DOM_DOCUMENT_POSITION_XXX 定数の組み合わせで、
33 * 例えば DOM_DOCUMENT_POSITION_PRECEDING | DOM_DOCUMENT_POSITION_CONTAINS のように
34 * 複数の意味を持つことがあります。
35 *
36 * @param DOMNode $baseNode 比較の基準となるノード。
37 * @param DOMNode $otherNode $baseNode に対して位置を比較するノード。
38 * @return string ノード間の位置関係を表す説明文。
39 */
40function describeNodePosition(DOMNode $baseNode, DOMNode $otherNode): string
41{
42    // ノード名を人間が読める形式で取得します。
43    // #text や #entity のような内部名を避け、可能な限り具体的な要素名や内容を使用します。
44    $getBaseNodeName = function (DOMNode $node): string {
45        if ($node->nodeType === XML_ELEMENT_NODE) {
46            return "<{$node->tagName}> (Element)";
47        } elseif ($node->nodeType === XML_TEXT_NODE) {
48            // テキストノードの内容が長すぎる場合を考慮
49            $value = mb_substr($node->nodeValue, 0, 20);
50            if (mb_strlen($node->nodeValue) > 20) {
51                $value .= '...';
52            }
53            return "'{$value}' (Text Node)";
54        } elseif ($node->nodeType === XML_ENTITY_REF_NODE) {
55            return "&{$node->nodeName}; (Entity Reference)";
56        }
57        return "{$node->nodeName} (Node Type: {$node->nodeType})";
58    };
59
60    $baseNodeName = $getBaseNodeName($baseNode);
61    $otherNodeName = $getBaseNodeName($otherNode);
62
63    // DOMEntityReference::compareDocumentPosition を呼び出し
64    // このメソッドはDOMNodeクラスのメソッドですが、DOMEntityReferenceインスタンスから呼び出しています。
65    $position = $baseNode->compareDocumentPosition($otherNode);
66
67    $resultDescription = "ノード '{$otherNodeName}' はノード '{$baseNodeName}' に対して ";
68    $descriptions = [];
69
70    // 戻り値のビットマスクをDOM_DOCUMENT_POSITION_XXX定数と比較し、意味を解釈します。
71    if ($position === 0) {
72        $descriptions[] = "同じ位置にあります (自身)";
73    } else {
74        if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
75            $descriptions[] = "ドキュメント内で接続されていません (互いの祖先でも子孫でもない)";
76        }
77        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
78            $descriptions[] = "前にあります (ドキュメント順で、自身より前)";
79        }
80        if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
81            $descriptions[] = "後ろにあります (ドキュメント順で、自身より後)";
82        }
83        if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
84            $descriptions[] = "自身を含んでいます (自身がそのノードの祖先)";
85        }
86        if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
87            $descriptions[] = "自身に含まれています (自身がそのノードの子孫)";
88        }
89        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
90            $descriptions[] = "実装固有の比較結果です";
91        }
92    }
93
94    $resultDescription .= implode("、", $descriptions);
95
96    return $resultDescription . ".";
97}
98
99// ==============================================================================
100// サンプルコード本体
101// ==============================================================================
102
103// 新しい DOMDocument を作成し、XML の構造をプログラム的に構築します。
104// 実際のXMLファイルからロードした場合、DOMEntityReference ノードは通常自動的に展開されてしまい、
105// ツリー内に明示的に存在しないため、ここでは createEntityReference() を使用します。
106$dom = new DOMDocument('1.0', 'UTF-8');
107$dom->formatOutput = true; // 出力を見やすく整形します
108
109// ルート要素を作成し、ドキュメントに追加します。
110$root = $dom->createElement('root');
111$dom->appendChild($root);
112
113// 子要素 <item> を作成し、ルート要素に追加します。
114$itemElement = $dom->createElement('item');
115$root->appendChild($itemElement);
116
117// テキストノードを作成し、<item> 要素に追加します。
118$textNode1 = $dom->createTextNode('Hello ');
119$itemElement->appendChild($textNode1);
120
121// DOMEntityReference ノードを作成し、<item> 要素に追加します。
122// createEntityReference() を使用することで、比較対象となるエンティティ参照ノードを
123// 確実にDOMツリー内に配置できます。
124$entityRef = $dom->createEntityReference('myEntity');
125$itemElement->appendChild($entityRef);
126
127// 別のテキストノードを作成し、<item> 要素に追加します。
128$textNode2 = $dom->createTextNode(' World!');
129$itemElement->appendChild($textNode2);
130
131// 別の要素 <anotherItem> を作成し、ルート要素に追加します。
132$anotherItemElement = $dom->createElement('anotherItem', 'Some content');
133$root->appendChild($anotherItemElement);
134
135// 作成されたDOMツリーをXML形式で出力し、構造を確認します (デバッグ用)。
136// echo "--- DOM ツリーの構造 ---" . PHP_EOL;
137// echo $dom->saveXML();
138// echo "------------------------" . PHP_EOL . PHP_EOL;
139
140
141// 様々なノードの組み合わせについて、DOMEntityReference ノードを基準として位置関係を比較します。
142echo "--- ノードの位置比較結果 (基準ノード: &myEntity; (Entity Reference)) ---" . PHP_EOL;
143
144// 1. エンティティ参照ノードと、その前のテキストノードを比較
145echo describeNodePosition($entityRef, $textNode1) . PHP_EOL;
146
147// 2. エンティティ参照ノードと、その後のテキストノードを比較
148echo describeNodePosition($entityRef, $textNode2) . PHP_EOL;
149
150// 3. エンティティ参照ノードと、その親要素を比較
151echo describeNodePosition($entityRef, $itemElement) . PHP_EOL;
152
153// 4. エンティティ参照ノードと、同じ親を持つ別の要素を比較 (ドキュメント順で後にある)
154echo describeNodePosition($entityRef, $anotherItemElement) . PHP_EOL;
155
156// 5. エンティティ参照ノードと、ドキュメントのルート要素を比較 (祖先)
157echo describeNodePosition($entityRef, $root) . PHP_EOL;
158
159// 6. エンティティ参照ノード自身を比較
160echo describeNodePosition($entityRef, $entityRef) . PHP_EOL;
161
162// (参考) 基準ノードがエンティティ参照ノードではない場合の比較
163echo PHP_EOL . "--- 参考: 基準ノードが異なる場合の比較 ---" . PHP_EOL;
164// itemElementがentityRefを含んでいることを確認
165echo describeNodePosition($itemElement, $entityRef) . PHP_EOL;
166// rootがentityRefを含んでいることを確認
167echo describeNodePosition($root, $entityRef) . PHP_EOL;

DOMEntityReference::compareDocumentPositionメソッドは、PHPのDOM拡張機能で、2つのDOMノードがドキュメント内でどのような位置関係にあるかを比較するために利用されます。このメソッドは、呼び出し元のDOMEntityReferenceノードを基準として、引数で指定されたDOMNode $otherとの相対的な位置を整数値で返します。

戻り値はビットマスク形式で、ノードが基準ノードの前に位置するか、後ろに位置するか、基準ノードに含まれる（子孫である）か、あるいは基準ノードがそのノードを含む（祖先である）か、さらにはドキュメント内で全く関連がないか、といった複数の状態を組み合わせて示します。

サンプルコードでは、DOMDocumentを使ってXMLの構造をプログラム的に構築し、特にcreateEntityReferenceメソッドを用いてDOMEntityReferenceノードを明示的に生成しています。そして、このエンティティ参照ノードを基準に、同じ階層のテキストノードや別の要素、さらには親要素やルート要素といった様々なノードとの位置関係を比較しています。戻り値のビットマスクは、専用の関数describeNodePositionによって分かりやすい文字列に変換され、それぞれの比較結果が具体的に説明されます。このメソッドは、DOMツリー内でのノードの正確な位置関係を把握し、複雑なドキュメント操作を行う際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * PHPのDOMEntityReference::compareDocumentPositionメソッドの使用例を示します。
5 *
6 * この関数は、2つのDOMノード間の位置関係を比較し、その結果をシステムエンジニアを目指す
7 * 初心者にも分かりやすいように説明します。
8 * phpdocumentorによるドキュメント生成を意識し、適切なPHPDocコメントを含みます。
9 *
10 * @param string $xmlString 比較に使用するXML文字列。内部DTDサブセットでエンティティ 'myentity' の定義が必要です。
11 * @return void
12 * @throws DOMException DOM操作中にエラーが発生した場合。
13 */
14function demonstrateCompareDocumentPosition(string $xmlString): void
15{
16    // DOMDocumentのインスタンスを作成
17    $dom = new DOMDocument();
18    // エラーハンドリングを有効にする
19    $dom->strictErrorChecking = true;
20
21    // XMLをロード (実体参照の定義を含む)
22    if (!@$dom->loadXML($xmlString)) {
23        // @エラー抑制演算子は、XMLロードエラーがログに出力されるのを防ぎます。
24        // get_last_error()などで詳細なエラー情報を取得することも可能ですが、
25        // 初心者向けにはシンプルなメッセージで十分とします。
26        echo "エラー: XMLのロードに失敗しました。\n";
27        return;
28    }
29
30    // ドキュメントツリーからノードを取得
31    $rootElement = $dom->documentElement;
32    if ($rootElement === null) {
33        echo "エラー: ルート要素が見つかりません。\n";
34        return;
35    }
36
37    // 'child1' 要素を取得
38    $child1Element = $dom->getElementsByTagName('child1')->item(0);
39    if ($child1Element === null) {
40        echo "エラー: 'child1' 要素が見つかりません。\n";
41        return;
42    }
43
44    // 'myentity' という名前の実体参照ノードを作成
45    // このメソッドはDTDで定義されたエンティティ名を参照します。
46    // サンプルXMLで 'myentity' が定義されている必要があります。
47    $entityReferenceNode = $dom->createEntityReference('myentity');
48    if ($entityReferenceNode === false) {
49        echo "エラー: エンティティ参照 'myentity' の作成に失敗しました。DTDに定義されているか確認してください。\n";
50        return;
51    }
52
53    // 作成した実体参照ノードをルート要素に追加
54    // これにより、DOMツリー上でノードが配置され、比較が可能になります。
55    $rootElement->appendChild($entityReferenceNode);
56
57
58    echo "--- DOMEntityReference::compareDocumentPosition のデモンストレーション ---\n";
59
60    // 1. DOMEntityReference と同じ階層の DOMElement を比較
61    echo "\n[1. ノードA (DOMEntityReference 'myentity') と ノードB (DOMElement 'child1') の比較]\n";
62    // $entityReferenceNodeは$child1Elementの後にDOMツリーに追加されたため、
63    // $entityReferenceNodeから見ると$child1Elementは先行するノードです。
64    $position1 = $entityReferenceNode->compareDocumentPosition($child1Element);
65    echo "結果: " . getPositionDescription($position1) . "\n";
66    echo "期待される結果: DOM_DOCUMENT_POSITION_PRECEDING (引数ノードが呼び出し元ノードの前に現れる)\n";
67
68    // 2. DOMEntityReference とその親ノードを比較
69    echo "\n[2. ノードA (DOMEntityReference 'myentity') と ノードB (DOMElement 'root') の比較]\n";
70    // $entityReferenceNodeは$rootElementの子孫であるため、
71    // $entityReferenceNodeから見ると$rootElementは自身を含むノードです。
72    $position2 = $entityReferenceNode->compareDocumentPosition($rootElement);
73    echo "結果: " . getPositionDescription($position2) . "\n";
74    echo "期待される結果: DOM_DOCUMENT_POSITION_CONTAINS (引数ノードが呼び出し元ノードの子孫である)\n";
75
76    // 3. 親ノードと DOMEntityReference を比較（逆のパターン）
77    echo "\n[3. ノードA (DOMElement 'root') と ノードB (DOMEntityReference 'myentity') の比較]\n";
78    // $rootElementから見ると$entityReferenceNodeは自身に含まれるノードです。
79    $position3 = $rootElement->compareDocumentPosition($entityReferenceNode);
80    echo "結果: " . getPositionDescription($position3) . "\n";
81    echo "期待される結果: DOM_DOCUMENT_POSITION_CONTAINED_BY (引数ノードが呼び出し元ノードの祖先である)\n";
82
83    // 4. 自分自身との比較
84    echo "\n[4. ノードA (DOMEntityReference 'myentity') と ノードB (DOMEntityReference 'myentity') の比較]\n";
85    // 同じノードを比較した場合、結果は0 (DOM_DOCUMENT_POSITION_SAME_NODE) になります。
86    $position4 = $entityReferenceNode->compareDocumentPosition($entityReferenceNode);
87    echo "結果: " . getPositionDescription($position4) . "\n";
88    echo "期待される結果: ノードは同じである (DOM_DOCUMENT_POSITION_SAME_NODE)\n";
89
90    // 5. 別のドキュメントのノードとの比較
91    echo "\n[5. ノードA (DOMEntityReference 'myentity') と ノードB (別のドキュメントのノード) の比較]\n";
92    $anotherDom = new DOMDocument();
93    // 別のDOMドキュメントをロード
94    if (!@$anotherDom->loadXML('<another_root><another_child/></another_root>')) {
95        echo "エラー: 別のXMLドキュメントのロードに失敗しました。\n";
96        return;
97    }
98    $anotherRoot = $anotherDom->documentElement;
99    // 異なるドキュメントに属するノードは「切断されている」と見なされます。
100    $position5 = $entityReferenceNode->compareDocumentPosition($anotherRoot);
101    echo "結果: " . getPositionDescription($position5) . "\n";
102    echo "期待される結果: DOM_DOCUMENT_POSITION_DISCONNECTED (ノードは異なるドキュメントに属するか、互いにツリー上で関連がない)\n";
103}
104
105/**
106 * compareDocumentPosition メソッドの戻り値 (整数値) を人間が読める文字列に変換します。
107 *
108 * このヘルパー関数は、結果のビットフラグを解釈し、それぞれの意味を説明します。
109 *
110 * @param int $position compareDocumentPosition メソッドの戻り値。
111 * @return string 解釈された位置関係の説明。
112 */
113function getPositionDescription(int $position): string
114{
115    $descriptions = [];
116
117    // 各定数はビットフラグとして定義されています。
118    // 論理AND演算子 (&) を使って、どのフラグが立っているかを確認します。
119
120    if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
121        $descriptions[] = "DOM_DOCUMENT_POSITION_DISCONNECTED (ノードは異なるドキュメントに属するか、互いにツリー上で関連がない)";
122    }
123    if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
124        $descriptions[] = "DOM_DOCUMENT_POSITION_PRECEDING (引数ノードが呼び出し元ノードの前に現れる)";
125    }
126    if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
127        $descriptions[] = "DOM_DOCUMENT_POSITION_FOLLOWING (引数ノードが呼び出し元ノードの後に現れる)";
128    }
129    if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
130        $descriptions[] = "DOM_DOCUMENT_POSITION_CONTAINS (引数ノードが呼び出し元ノードの子孫である)";
131    }
132    if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
133        $descriptions[] = "DOM_DOCUMENT_POSITION_CONTAINED_BY (引数ノードが呼び出し元ノードの祖先である)";
134    }
135    // DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20) は、実装固有の情報を示すフラグですが、
136    // 通常のユースケースでは上記のフラグで十分な情報が得られるため、ここでは省略します。
137
138    // どのフラグも立っていない場合 (0x00) は同じノードを示します。
139    if (empty($descriptions) && $position === 0) {
140        $descriptions[] = "ノードは同じである (DOM_DOCUMENT_POSITION_SAME_NODE)";
141    }
142
143    return implode(" | ", $descriptions);
144}
145
146// サンプルXML文字列
147// ここでは、DOMDocument::createEntityReference('myentity') が参照できるように、
148// 内部DTDサブセットでエンティティ 'myentity' を定義しています。
149$sampleXml = <<<XML
150<!DOCTYPE root [
151    <!ENTITY myentity "My special entity text.">
152]>
153<root>
154    <child1>First child.</child1>
155    <child2>Second child.</child2>
156</root>
157XML;
158
159// 関数を実行してデモンストレーション
160try {
161    demonstrateCompareDocumentPosition($sampleXml);
162} catch (DOMException $e) {
163    echo "DOM操作中にエラーが発生しました: " . $e->getMessage() . "\n";
164} catch (Exception $e) {
165    echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
166}

PHPのDOMEntityReference::compareDocumentPositionメソッドは、XMLのDOMツリー上での2つのノード間の位置関係を比較するために使用されます。このメソッドは、引数として比較対象となるDOMNodeオブジェクトを受け取ります。戻り値は整数値で、これはビットフラグとして、対象ノードが呼び出し元ノードに対して「先行している」「後続している」「自身を包含している」「自身に包含されている」「異なるドキュメントに属している」といった複数の位置関係を示す場合があります。

サンプルコードでは、まずDTDでエンティティが定義されたXMLを読み込み、DOMEntityReferenceのインスタンスを含む複数のノードを準備します。その後、このエンティティ参照ノードを基準として、他のノード（同じ階層の要素、親要素、自分自身、別のDOMドキュメントのノード）との位置関係をcompareDocumentPositionメソッドで比較しています。特に、戻り値がビットフラグであるため、その意味を初心者にも分かりやすく理解できるよう、getPositionDescriptionというヘルパー関数を用いて、それぞれのフラグが示す具体的な意味を文字列で説明しています。これにより、DOMツリー内のノードの相対的な位置をプログラムで確認し、その結果に基づいて処理を行う方法を実践的に学ぶことができます。