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

Copy
1<?php
2
3/**
4 * Dom\Element::compareDocumentPosition() メソッドの使用例を示します。
5 *
6 * この関数は、PHP DOM拡張機能を使用してXMLドキュメントを作成し、
7 * ドキュメント内の異なる要素間の相対的な位置関係を比較します。
8 * compareDocumentPosition メソッドの戻り値をビットマスクとして解釈し、
9 * その意味をわかりやすく出力します。
10 *
11 * システムエンジニアを目指す初心者の方にも理解しやすいように、
12 * ドキュメントの作成から要素の選択、比較結果の解釈までを簡潔に示します。
13 *
14 * このコードは、追加のComposerパッケージを必要とせず、PHP標準のDOM拡張機能を使用します。
15 * PHPDocコメントは、phpdocumentorのようなツールでドキュメントを生成する際の参考になります。
16 *
17 * @return void
18 */
19function demonstrateDomElementComparison(): void
20{
21    // 1. XMLドキュメントの作成と要素の追加
22    // Dom\Document クラスのインスタンスを作成します。これはXMLドキュメント全体を表します。
23    $dom = new Dom\Document('1.0', 'UTF-8');
24    // ルート要素 '<root>' を作成し、ドキュメントに追加します。
25    $root = $dom->createElement('root');
26    $dom->appendChild($root);
27
28    // 子要素 '<child1>' を作成し、ルート要素に追加します。
29    $child1 = $dom->createElement('child1');
30    $root->appendChild($child1);
31
32    // 孫要素 '<grandchild>' を作成し、子要素1に追加します。
33    $grandchild = $dom->createElement('grandchild');
34    $child1->appendChild($grandchild);
35
36    // 別の兄弟要素 '<child2>' を作成し、ルート要素に追加します。
37    $child2 = $dom->createElement('child2');
38    $root->appendChild($child2);
39
40    // ドキュメントに接続されていない別の要素 '<anotherElement>' を作成します。
41    // この要素はDOMツリーの一部ではないため、比較結果が異なります。
42    $anotherElement = $dom->createElement('anotherElement');
43
44    echo "--- Dom\\Element::compareDocumentPosition の使用例 ---\n";
45    echo "比較対象の要素の構造:\n";
46    echo "  <root>\n";
47    echo "    <child1>\n";
48    echo "      <grandchild/>\n";
49    echo "    </child1>\n";
50    echo "    <child2/>\n";
51    echo "  </root>\n";
52    echo "  <anotherElement/> (ドキュメントに未接続)\n\n";
53
54    // 2. 異なる要素間の比較を実行し、結果を出力
55
56    // $root と $child1 の比較: $rootは$child1を包含しています。
57    displayComparisonResult($root, $child1, 'root', 'child1');
58
59    // $child1 と $root の比較 (逆方向): $child1は$rootに包含されています。
60    displayComparisonResult($child1, $root, 'child1', 'root');
61
62    // $child1 と $grandchild の比較: $child1は$grandchildを包含しています。
63    displayComparisonResult($child1, $grandchild, 'child1', 'grandchild');
64
65    // $grandchild と $child1 の比較 (逆方向): $grandchildは$child1に包含されています。
66    displayComparisonResult($grandchild, $child1, 'grandchild', 'child1');
67
68    // $child1 と $child2 の比較 (兄弟要素): $child1は$child2より前に位置します。
69    displayComparisonResult($child1, $child2, 'child1', 'child2');
70
71    // $child2 と $child1 の比較 (逆方向): $child2は$child1より後に位置します。
72    displayComparisonResult($child2, $child1, 'child2', 'child1');
73
74    // $root と $root 自身の比較: 同じノードです。
75    displayComparisonResult($root, $root, 'root', 'root');
76
77    // $root と $anotherElement の比較: $anotherElementはDOMツリーに接続されていないため、非接続と判断されます。
78    displayComparisonResult($root, $anotherElement, 'root', 'anotherElement (disconnected)');
79}
80
81/**
82 * 2つの Dom\Node オブジェクトを比較し、その結果を人間が読める形式で出力します。
83 *
84 * Dom\Element::compareDocumentPosition メソッドの戻り値（ビットマスク）を
85 * Dom\Node クラスの定数と比較し、要素間の関係性を説明します。
86 *
87 * @param Dom\Element $sourceNode 比較の基準となる要素。
88 * @param Dom\Node    $otherNode  比較対象の要素。
89 * @param string      $sourceName 基準となる要素の識別名 (出力用)。
90 * @param string      $otherName  比較対象の要素の識別名 (出力用)。
91 *
92 * @return void
93 */
94function displayComparisonResult(Dom\Element $sourceNode, Dom\Node $otherNode, string $sourceName, string $otherName): void
95{
96    // compareDocumentPosition メソッドを呼び出し、2つのノード間の相対位置を取得します。
97    // 戻り値はビットマスク (複数の関係性を同時に示す整数値) です。
98    $position = $sourceNode->compareDocumentPosition($otherNode);
99
100    echo sprintf("比較: '%s' と '%s'\n", $sourceName, $otherName);
101    // 結果のビットマスクを16進数形式で出力し、視覚的に分かりやすくします。
102    echo sprintf("  結果のビットマスク (16進数): 0x%02X\n", $position);
103    echo "  解釈:\n";
104
105    // 結果のビットマスクを Dom\Node の定数とビット論理積 (&) を使って解釈します。
106    // 各定数は特定の関係性を示すビットフラグです。
107
108    // Dom\Node::DOCUMENT_POSITION_SAME_NODE は 0x00 (0) です。
109    // positionが0の場合、両方のノードが同じであることを示します。
110    if ($position === Dom\Node::DOCUMENT_POSITION_SAME_NODE) {
111        echo "    - 両方のノードは同じです。\n";
112    }
113
114    // ノードが異なる文書に属しているか、DOMツリーに接続されていない場合 (0x01)。
115    if ($position & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
116        echo "    - ノードは異なる文書に属しているか、DOMツリーに接続されていません。\n";
117    }
118    // 比較対象のノード ($otherNode) が基準ノード ($sourceNode) のDOMツリー内で前に位置する場合 (0x02)。
119    if ($position & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
120        echo sprintf("    - '%s' は '%s' の前に位置します。\n", $otherName, $sourceName);
121    }
122    // 比較対象のノード ($otherNode) が基準ノード ($sourceNode) のDOMツリー内で後に位置する場合 (0x04)。
123    if ($position & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
124        echo sprintf("    - '%s' は '%s' の後に位置します。\n", $otherName, $sourceName);
125    }
126    // 基準ノード ($sourceNode) が比較対象のノード ($otherNode) を包含している場合 (0x08)。
127    if ($position & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
128        echo sprintf("    - '%s' は '%s' を包含しています。\n", $sourceName, $otherName);
129    }
130    // 基準ノード ($sourceNode) が比較対象のノード ($otherNode) によって包含されている場合 (0x10)。
131    if ($position & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
132        echo sprintf("    - '%s' は '%s' に包含されています。\n", $sourceName, $otherName);
133    }
134    echo "\n";
135}
136
137// スクリプトが直接実行された場合にのみ demonstrateDomElementComparison 関数を呼び出します。
138// これは、このファイルが他のスクリプトにrequireやincludeされたときに、
139// 自動的に関数が実行されるのを防ぐための一般的なパターンです。
140if (realpath($_SERVER['SCRIPT_FILENAME']) === realpath(__FILE__)) {
141    demonstrateDomElementComparison();
142}

PHP 8のDom\Element::compareDocumentPosition()メソッドは、XMLやHTMLドキュメント内の2つのDOMノード（要素やテキストなど）の相対的な位置関係を比較するために利用されます。このメソッドは、呼び出し元のDom\Elementインスタンスと、引数として渡されるDom\Node $otherオブジェクトを比較します。戻り値は整数値で、これは複数の関係性を示す「ビットマスク」として解釈されます。

提供されたサンプルコードでは、まずDom\Documentを用いて簡単なXMLドキュメントを作成し、root、child1、grandchild、child2といった要素を追加してツリー構造を構築しています。さらに、ドキュメントに接続されていない要素も用意されています。その後、これらの要素を様々な組み合わせでcompareDocumentPosition()メソッドに渡し、その結果を詳細に解説しています。戻り値のビットマスクは、Dom\Nodeクラスが定義する定数（例: DOCUMENT_POSITION_PRECEDING、DOCUMENT_POSITION_FOLLOWING、DOCUMENT_POSITION_CONTAINS、DOCUMENT_POSITION_DISCONNECTEDなど）とビット論理積（&）を使って解釈され、一方の要素がもう一方の前に位置するか、後に位置するか、包含しているか、あるいはドキュメント内で接続されていないかといった具体的な関係性が初心者にも分かりやすく出力されます。これにより、DOMツリーにおけるノード間の厳密な位置関係をプログラムで把握する方法が理解できます。

Copy
1<?php
2
3/**
4 * Dom\Element::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、DOMツリー内の異なるノード間の位置関係を比較し、
7 * その結果を人間が理解しやすい形式で表示します。
8 * システムエンジニアを目指す初心者が、DOMノード間の相対位置を
9 * プログラムでどのように判断できるかを学ぶのに役立ちます。
10 *
11 * PHP 8 以降で利用可能な Dom\Element クラスのメソッドを使用し、
12 * phpdocumentor が解析しやすいように適切なPHPDocコメントを記述しています。
13 */
14function demonstrateCompareDocumentPosition(): void
15{
16    // 1. DOM ドキュメントの作成
17    /** @var Dom\Document $doc DOMドキュメントのインスタンス */
18    $doc = new Dom\Document('1.0', 'UTF-8');
19    $doc->formatOutput = true; // 出力を見やすくするための設定
20
21    // 2. 要素の作成とDOMツリーの構築
22    /** @var Dom\Element $root ルート要素 */
23    $root = $doc->createElement('root');
24    $doc->appendChild($root);
25
26    /** @var Dom\Element $parent 親要素 */
27    $parent = $doc->createElement('parent');
28    $root->appendChild($parent);
29
30    /** @var Dom\Element $child1 最初の子供要素 */
31    $child1 = $doc->createElement('child1');
32    $parent->appendChild($child1);
33
34    /** @var Dom\Element $child2 2番目の子供要素（child1の兄弟） */
35    $child2 = $doc->createElement('child2');
36    $parent->appendChild($child2);
37
38    /** @var Dom\Element $grandchild 孫要素（child1の子） */
39    $grandchild = $doc->createElement('grandchild');
40    $child1->appendChild($grandchild);
41
42    // 別のDOMツリーの要素を作成し、比較対象として使用
43    /** @var Dom\Document $anotherDoc 別のDOMドキュメントのインスタンス */
44    $anotherDoc = new Dom\Document('1.0', 'UTF-8');
45    /** @var Dom\Element $anotherElement 別のDOMドキュメント内の要素 */
46    $anotherElement = $anotherDoc->createElement('anotherElement');
47    $anotherDoc->appendChild($anotherElement);
48
49    echo "--- DOM Tree Structure ---\n";
50    echo $doc->saveXML() . "\n";
51    echo "--------------------------\n\n";
52
53    // 3. compareDocumentPosition メソッドを使用したノード間の比較
54    // 基準となるノードを 'child1' とします。
55    /** @var Dom\Element $baseNode 比較の基準となるノード */
56    $baseNode = $child1;
57    echo "Base Node: <{$baseNode->tagName}>\n\n";
58
59    /**
60     * @var array<string, Dom\Node> $nodesToCompare 基準ノードと比較する他のノードの配列
61     * キーはノードの説明、値はDom\Nodeインスタンス
62     */
63    $nodesToCompare = [
64        'itself' => $baseNode,
65        'parent' => $parent,
66        'grandchild' => $grandchild,
67        'sibling (child2)' => $child2,
68        'root' => $root,
69        'another tree element' => $anotherElement,
70    ];
71
72    foreach ($nodesToCompare as $name => $otherNode) {
73        // Dom\Element::compareDocumentPosition は Dom\Node $other を引数に取ります。
74        // 戻り値は整数で、Dom\Node クラスの定数（ビットマスク）を使って解釈します。
75        /** @var int $position ノードの位置関係を示すビットマスク */
76        $position = $baseNode->compareDocumentPosition($otherNode);
77
78        echo "Comparing with '{$name}' (<{$otherNode->tagName}>):\n";
79        echo "  Raw result: {$position}\n";
80        echo "  Interpretation: ";
81        /** @var string[] $interpretations 解釈された位置関係の文字列配列 */
82        $interpretations = [];
83
84        // 戻り値のビットマスクを各定数とビット論理積（&）でチェックし解釈
85        // DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): ノードが同じツリーにない、または異なるサブツリーにある
86        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_DISCONNECTED) {
87            $interpretations[] = "DISCONNECTED (異なるツリーまたは関連性なし)";
88        }
89        // DOM_DOCUMENT_POSITION_PRECEDING (0x02): otherNodeがbaseNodeよりドキュメント順序で前に来る
90        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_PRECEDING) {
91            $interpretations[] = "PRECEDING (相手ノードが基準ノードより前)";
92        }
93        // DOM_DOCUMENT_POSITION_FOLLOWING (0x04): otherNodeがbaseNodeよりドキュメント順序で後に来る
94        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_FOLLOWING) {
95            $interpretations[] = "FOLLOWING (相手ノードが基準ノードより後)";
96        }
97        // DOM_DOCUMENT_POSITION_CONTAINS (0x08): baseNodeがotherNodeの祖先である
98        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_CONTAINS) {
99            $interpretations[] = "CONTAINS (基準ノードが相手ノードを含む)";
100        }
101        // DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): baseNodeがotherNodeの子孫である
102        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_CONTAINED_BY) {
103            $interpretations[] = "CONTAINED_BY (基準ノードが相手ノードに含まれる)";
104        }
105        // DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装依存のフラグ（通常は要素ノード間では稀）
106        if ($position & Dom\Node::DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
107            $interpretations[] = "IMPLEMENTATION_SPECIFIC (実装依存)";
108        }
109
110        // 自身と比較した場合 (戻り値が0)
111        if ($position === 0 && $baseNode === $otherNode) {
112            $interpretations[] = "SAME_NODE (同じノード)";
113        }
114
115        if (empty($interpretations)) {
116            $interpretations[] = "UNKNOWN_POSITION (不明な位置)";
117        }
118
119        echo implode(", ", $interpretations) . "\n\n";
120    }
121}
122
123// 関数の実行
124demonstrateCompareDocumentPosition();

このPHPサンプルコードは、Dom\ElementクラスのcompareDocumentPositionメソッドの使い方を、システムエンジニアを目指す初心者の方にも分かりやすく解説しています。このメソッドは、DOM（Document Object Model）ツリー内にある2つのノード間の相対的な位置関係を比較するために使用されます。

compareDocumentPositionメソッドは、比較対象となるDom\Node型のノードを引数として受け取り、比較結果を整数値で返します。この整数値は、複数の情報を含むビットマスクとなっており、Dom\Nodeクラスで定義されている定数（例: DOM_DOCUMENT_POSITION_DISCONNECTED、DOM_DOCUMENT_POSITION_PRECEDING、DOM_DOCUMENT_POSITION_CONTAINSなど）とビット論理積（&）を用いて、個々の位置関係を判定できます。

サンプルコードでは、まず複数の要素からなるDOMツリーを構築し、異なる階層や兄弟関係にあるノード、さらには全く別のDOMツリーに属するノードを用意しています。そして、特定のノードを基準として、これらのノードとの位置関係をcompareDocumentPositionメソッドで順に比較しています。例えば、「基準ノードが相手ノードを含むか」や「相手ノードが基準ノードよりドキュメント順序で前に来るか」、または「異なるツリーに属しているか」といった関係性をビットマスクから判別し、その結果を具体的に出力しています。

これにより、DOMを操作する際に、ノード間の相対的な位置をプログラムで正確に判断する方法を学ぶことができます。また、コード内のPHPDocコメントは、phpdocumentorのようなツールで解析されることを想定しており、コードの可読性向上と自動ドキュメント生成に役立ちます。