【PHP8.x】Dom\XMLDocument::DOCUMENT_POSITION_PRECEDING定数の使い方

Copy
1<?php
2
3/**
4 * Dom\Node::DOCUMENT_POSITION_PRECEDING 定数の使用方法を示すサンプルコードです。
5 * この定数は、DOMツリー内のノードの位置関係を比較する際に利用されます。
6 * compareDocumentPosition() メソッドの結果がこの定数を含む場合、比較対象のノードは
7 * 参照ノードよりDOMツリー上で物理的に前に位置することを意味します。
8 */
9function demonstrateDocumentPositionPreceding(): void
10{
11    // 新しいDOMドキュメントを作成します。
12    // PHP 8ではDOMDocumentクラスはDom\Documentのエイリアスとして機能します。
13    $document = new DOMDocument();
14    // 生成されるXMLの可読性を高めるため、フォーマットを有効にします。
15    $document->formatOutput = true;
16
17    // ルート要素 'root' を作成し、ドキュメントに追加します。
18    $rootElement = $document->createElement('root');
19    $document->appendChild($rootElement);
20
21    // 最初の要素 'first' を作成し、ルート要素に追加します。
22    $firstElement = $document->createElement('first');
23    $rootElement->appendChild($firstElement);
24
25    // 2番目の要素 'second' を作成し、ルート要素に追加します。
26    $secondElement = $document->createElement('second');
27    $rootElement->appendChild($secondElement);
28
29    echo "--- Dom\Node::DOCUMENT_POSITION_PRECEDING 定数の動作確認 ---\n\n";
30
31    // ケース1: 'first' 要素 ('first') を 'second' 要素 ('second') と比較します。
32    // 'first' 要素はDOMツリー内で 'second' 要素より前に位置するため、
33    // DOCUMENT_POSITION_PRECEDING が含まれるはずです。
34    echo "1. 'first' 要素と 'second' 要素を比較:\n";
35    $positionResult1 = $firstElement->compareDocumentPosition($secondElement);
36
37    if ($positionResult1 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
38        echo "   -> 結果: 'first' 要素は 'second' 要素より前に位置します。\n";
39    } else {
40        echo "   -> 結果: 'first' 要素は 'second' 要素より前に位置しません。\n";
41    }
42    echo "\n";
43
44    // ケース2: 'second' 要素 ('second') を 'first' 要素 ('first') と比較します。
45    // 'second' 要素は 'first' 要素より後に位置するため、
46    // DOCUMENT_POSITION_PRECEDING は含まれません。
47    echo "2. 'second' 要素と 'first' 要素を比較:\n";
48    $positionResult2 = $secondElement->compareDocumentPosition($firstElement);
49
50    if ($positionResult2 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
51        echo "   -> 結果: 'second' 要素は 'first' 要素より前に位置します。\n";
52    } else {
53        echo "   -> 結果: 'second' 要素は 'first' 要素より前に位置しません。\n";
54        // この場合、DOCUMENT_POSITION_FOLLOWING が含まれている可能性が高いです。
55    }
56    echo "\n";
57
58    // ケース3: 'first' 要素 ('first') をそれ自身と比較します。
59    // ノードはそれ自身より前に位置することはないため、
60    // DOCUMENT_POSITION_PRECEDING は含まれません。
61    echo "3. 'first' 要素とそれ自身を比較:\n";
62    $positionResult3 = $firstElement->compareDocumentPosition($firstElement);
63
64    if ($positionResult3 & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
65        echo "   -> 結果: 'first' 要素はそれ自身より前に位置します。\n";
66    } else {
67        echo "   -> 結果: 'first' 要素はそれ自身より前に位置しません。\n";
68        // 実際には DOCUMENT_POSITION_IDENTICAL が含まれます。
69    }
70    echo "\n";
71}
72
73// 関数を実行して、上記で定義した動作を確認します。
74demonstrateDocumentPositionPreceding();

Dom\Node::DOCUMENT_POSITION_PRECEDING定数は、PHPのDOM（Document Object Model）操作において、XMLやHTMLなどのツリー構造内で二つのノードがどのような位置関係にあるかを比較する際に利用されます。この定数自体に引数や戻り値はありませんが、主にDom\NodeクラスのcompareDocumentPosition()メソッドと組み合わせて使用されます。

compareDocumentPosition()メソッドは、比較対象のノードが参照ノードに対してどの位置にあるかを示す整数値を返します。この戻り値に対して、ビット論理積（&）演算子を用いてDom\Node::DOCUMENT_POSITION_PRECEDINGを評価し、結果が真となる場合、比較対象のノードは参照ノードよりもDOMツリー上で物理的に先に（前に）位置していることを意味します。

例えば、兄弟関係にある要素を比較する際に、どちらが先に定義されているかを判別できます。サンプルコードでは、DOMDocumentを作成し、複数の要素を追加した後、それらの要素間の位置関係をcompareDocumentPosition()で比較しています。その結果をDOCUMENT_POSITION_PRECEDINGで確認することで、どのノードが別のノードより先にツリー内に存在するかを具体的に把握する仕組みが示されています。これにより、DOMツリー内での要素の前後関係を正確に判断する際に役立ちます。

Copy
1<?php
2
3/**
4 * Demonstrates the usage of the DOM_DOCUMENT_POSITION_PRECEDING constant in PHP 8.
5 *
6 * This function creates a simple XML document with multiple elements and
7 * then uses Dom\Node::compareDocumentPosition() to determine the relative
8 * position of different nodes within the document tree.
9 * The DOM_DOCUMENT_POSITION_PRECEDING constant is used to check if a node
10 * precedes another.
11 *
12 * @param string $rootTagName         The tag name for the root element of the XML document.
13 * @param string $childTagNamePrefix  The prefix for the tag names of child elements.
14 * @return void
15 */
16function demonstrateDocumentPositionPreceding(string $rootTagName = 'root', string $childTagNamePrefix = 'item'): void
17{
18    // 1. 新しい Dom\Document インスタンスを作成します。
19    // PHP 8では、DOM拡張はDom名前空間に属しています。
20    $document = new Dom\Document('1.0', 'UTF-8');
21    $document->formatOutput = true; // 生成されるXMLを見やすく整形します
22
23    // 2. ルート要素を作成し、ドキュメントに追加します。
24    $rootElement = $document->createElement($rootTagName);
25    $document->appendChild($rootElement);
26
27    // 3. 複数の子要素を作成し、ルート要素に順番に追加します。
28    // ノードの追加順序が比較結果に影響します。
29    $nodeA = $document->createElement($childTagNamePrefix . 'A');
30    $rootElement->appendChild($nodeA);
31
32    $nodeB = $document->createElement($childTagNamePrefix . 'B');
33    $rootElement->appendChild($nodeB);
34
35    $nodeC = $document->createElement($childTagNamePrefix . 'C');
36    $rootElement->appendChild($nodeC);
37
38    echo "--- 生成されたXMLドキュメント ---\n";
39    echo $document->saveXML();
40    echo "-------------------------------\n\n";
41
42    // 4. Dom\Node::compareDocumentPosition() メソッドを使ってノードの位置を比較します。
43    // このメソッドは、比較対象のノード（$thisのインスタンス）と参照ノードの相対的な位置を
44    // 示すビットマスク（数値）を返します。
45    // DOM_DOCUMENT_POSITION_PRECEDING は、比較対象のノードが参照ノードより
46    // 前に位置する場合に、戻り値のビットマスクに含まれる定数です。
47
48    echo "--- ノード位置の比較結果 ---\n";
49
50    // 例 1: nodeA と nodeB の比較
51    // nodeA は文書構造上、nodeB の前に位置します。
52    // $nodeA->compareDocumentPosition($nodeB) は、nodeAがnodeBの前に位置するかどうかを示します。
53    $comparisonAB = $nodeA->compareDocumentPosition($nodeB);
54    echo "比較: '{$nodeA->nodeName}' と '{$nodeB->nodeName}'\n";
55    echo "  戻り値のビットマスク: " . $comparisonAB . "\n";
56    if ($comparisonAB & DOM_DOCUMENT_POSITION_PRECEDING) {
57        echo "  -> '{$nodeA->nodeName}' は '{$nodeB->nodeName}' の**前に位置します**。\n";
58    } else {
59        echo "  -> '{$nodeA->nodeName}' は '{$nodeB->nodeName}' の前に位置しません。\n";
60    }
61    echo "\n";
62
63    // 例 2: nodeB と nodeA の比較
64    // nodeB は文書構造上、nodeA の後に位置します。
65    // $nodeB->compareDocumentPosition($nodeA) は、nodeBがnodeAの前に位置するかどうかを示します。
66    $comparisonBA = $nodeB->compareDocumentPosition($nodeA);
67    echo "比較: '{$nodeB->nodeName}' と '{$nodeA->nodeName}'\n";
68    echo "  戻り値のビットマスク: " . $comparisonBA . "\n";
69    if ($comparisonBA & DOM_DOCUMENT_POSITION_PRECEDING) {
70        echo "  -> '{$nodeB->nodeName}' は '{$nodeA->nodeName}' の**前に位置します**。(これは誤りです)\n";
71    } else {
72        echo "  -> '{$nodeB->nodeName}' は '{$nodeA->nodeName}' の前に位置しません。(正しい)\n";
73        // 実際には DOM_DOCUMENT_POSITION_FOLLOWING (後続) が含まれます。
74        if ($comparisonBA & DOM_DOCUMENT_POSITION_FOLLOWING) {
75            echo "  (代わりに、'{$nodeB->nodeName}' は '{$nodeA->nodeName}' の**後に位置します**)\n";
76        }
77    }
78    echo "\n";
79
80    // 例 3: nodeC と rootElement の比較
81    // nodeC は rootElement の子孫であり、その中に含まれます。直接の「前に位置する」関係ではありません。
82    $comparisonCRoot = $nodeC->compareDocumentPosition($rootElement);
83    echo "比較: '{$nodeC->nodeName}' と '{$rootElement->nodeName}'\n";
84    echo "  戻り値のビットマスク: " . $comparisonCRoot . "\n";
85    if ($comparisonCRoot & DOM_DOCUMENT_POSITION_PRECEDING) {
86        echo "  -> '{$nodeC->nodeName}' は '{$rootElement->nodeName}' の**前に位置します**。(これは誤りです)\n";
87    } else {
88        echo "  -> '{$nodeC->nodeName}' は '{$rootElement->nodeName}' の前に位置しません。(正しい)\n";
89        // 代わりに DOM_DOCUMENT_POSITION_CONTAINED_BY (含まれる) が含まれるはずです。
90        if ($comparisonCRoot & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
91            echo "  (代わりに、'{$nodeC->nodeName}' は '{$rootElement->nodeName}' に**含まれています**)\n";
92        }
93    }
94    echo "\n";
95}
96
97// サンプル関数を実行します。
98demonstrateDocumentPositionPreceding();
99

このPHPサンプルコードは、PHP 8のDOM拡張機能において、XMLドキュメント内のノードの相対的な位置を判断するためのDOM_DOCUMENT_POSITION_PRECEDING定数の使い方を実演しています。

まず、Dom\Documentインスタンスを作成し、ルート要素とその子要素を順に配置してXML構造を構築します。次に、各ノードのインスタンスが持つcompareDocumentPosition()メソッドを使用し、二つのノードが文書ツリー上でどのような位置関係にあるかを比較します。

DOM_DOCUMENT_POSITION_PRECEDING定数は、あるノードが別のノード（比較対象のメソッドを呼び出すノード）よりも、文書構造上「前に位置する」場合に、compareDocumentPosition()メソッドが返す結果（ビットマスク）に含まれるフラグです。サンプルコードでは、この定数とcompareDocumentPosition()の戻り値をビット論理積（&）で評価することで、ノードが先行しているかを判定しています。例えば、itemAがitemBより前に作成されていれば、itemA->compareDocumentPosition(itemB)の結果にこの定数が含まれることを示しています。

demonstrateDocumentPositionPreceding関数は、XMLドキュメントのルート要素名と子要素名のプレフィックスを引数として受け取り、柔軟なテストが可能です。この関数は特定の戻り値を返しませんが、実行結果を画面に出力することで、ノード位置比較の具体的な挙動を視覚的に確認できます。