【PHP8.x】DOMText::DOCUMENT_POSITION_FOLLOWING定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドを使用して、
5 * 2つのDOMノードのドキュメント内での相対的な位置関係を比較するサンプルコードです。
6 * DOM_DOCUMENT_POSITION_PRECEDING および DOM_DOCUMENT_POSITION_FOLLOWING 定数の使用例を示します。
7 *
8 * システムエンジニアを目指す初心者向けに、簡潔で分かりやすいコードを目指します。
9 */
10function demonstrateNodePositionComparison(): void
11{
12    // 新しいDOMドキュメントを作成
13    $dom = new DOMDocument();
14    // サンプルXMLを読み込み
15    // <root>
16    //   <first>テキスト1</first>
17    //   <second>テキスト2</second>
18    // </root>
19    $dom->loadXML('<root><first>テキスト1</first><second>テキスト2</second></root>');
20
21    // 比較対象となるDOMElementノードを取得
22    // これらのノードはDOMNodeクラスを継承しています。
23    $nodeFirst = $dom->getElementsByTagName('first')->item(0);
24    $nodeSecond = $dom->getElementsByTagName('second')->item(0);
25
26    // ノードが正しく取得できたかを確認
27    if ($nodeFirst === null || $nodeSecond === null) {
28        echo "エラー: 'first' または 'second' ノードが見つかりませんでした。\n";
29        return;
30    }
31
32    echo "--- ノードの位置関係比較のデモンストレーション ---\n\n";
33
34    // ----------------------------------------------------
35    // 1. first ノードから見て second ノードの位置を比較
36    //    (DOM_DOCUMENT_POSITION_FOLLOWING の例)
37    // ----------------------------------------------------
38    echo "1. '{$nodeFirst->nodeName}' ノードから見て '{$nodeSecond->nodeName}' ノードを比較:\n";
39    // compareDocumentPosition() は、呼び出し元ノード (nodeFirst) から見て
40    // 引数で渡されたノード (nodeSecond) の位置関係を示すビットマスクを返します。
41    $positionFromFirst = $nodeFirst->compareDocumentPosition($nodeSecond);
42
43    if ($positionFromFirst & DOM_DOCUMENT_POSITION_FOLLOWING) {
44        // DOM_DOCUMENT_POSITION_FOLLOWING は、比較対象ノード (nodeSecond) が
45        // 呼び出し元ノード (nodeFirst) の後にドキュメント内で現れることを示します。
46        echo "  - 結果: '{$nodeSecond->nodeName}' は '{$nodeFirst->nodeName}' の**後に**位置しています。\n";
47    } else {
48        echo "  - 結果: 期待される DOM_DOCUMENT_POSITION_FOLLOWING ではありませんでした。 (取得値: {$positionFromFirst})\n";
49    }
50    echo "\n";
51
52    // ----------------------------------------------------
53    // 2. second ノードから見て first ノードの位置を比較
54    //    (DOM_DOCUMENT_POSITION_PRECEDING の例 - キーワードに関連)
55    // ----------------------------------------------------
56    echo "2. '{$nodeSecond->nodeName}' ノードから見て '{$nodeFirst->nodeName}' ノードを比較:\n";
57    $positionFromSecond = $nodeSecond->compareDocumentPosition($nodeFirst);
58
59    if ($positionFromSecond & DOM_DOCUMENT_POSITION_PRECEDING) {
60        // DOM_DOCUMENT_POSITION_PRECEDING は、比較対象ノード (nodeFirst) が
61        // 呼び出し元ノード (nodeSecond) の前にドキュメント内で現れることを示します。
62        echo "  - 結果: '{$nodeFirst->nodeName}' は '{$nodeSecond->nodeName}' の**前に**位置しています。\n";
63    } else {
64        echo "  - 結果: 期待される DOM_DOCUMENT_POSITION_PRECEDING ではありませんでした。 (取得値: {$positionFromSecond})\n";
65    }
66    echo "\n";
67
68    // ----------------------------------------------------
69    // 3. 同じノードを比較した場合
70    // ----------------------------------------------------
71    echo "3. 同じノード ('{$nodeFirst->nodeName}') を比較:\n";
72    $positionSelf = $nodeFirst->compareDocumentPosition($nodeFirst);
73    if ($positionSelf === 0) {
74        // 同じノードを比較した場合、関係性を示すフラグは何も立たないため、結果は0となります。
75        echo "  - 結果: 同じノードを比較した場合、結果は0となります。\n";
76    } else {
77        echo "  - 結果: 期待される0ではありませんでした。 (取得値: {$positionSelf})\n";
78    }
79    echo "\n";
80}
81
82// 関数を実行して、ノードの位置関係比較のデモンストレーションを開始
83demonstrateNodePositionComparison();
84

このサンプルコードは、PHPのDOM拡張機能を使用し、XMLなどのドキュメントツリー内で2つのDOMノードが互いにどのような位置関係にあるかをプログラムで判断する方法を示しています。

中心となるのはDOMNode::compareDocumentPosition()メソッドです。このメソッドは、呼び出し元ノードから見て引数で指定した比較対象ノードがどこに位置するかを、整数値（ビットマスク）として返します。戻り値は複数の位置関係を示すフラグの組み合わせであり、特定の関係性を確認するためにDOM_DOCUMENT_POSITION_FOLLOWINGやDOM_DOCUMENT_POSITION_PRECEDINGといった定数を使って判定します。

DOM_DOCUMENT_POSITION_FOLLOWING定数は、比較対象ノードが呼び出し元ノードのドキュメントフロー上で後に出現する場合に、戻り値に含まれるフラグです。一方、キーワードにも関連するDOM_DOCUMENT_POSITION_PRECEDING定数は、比較対象ノードが呼び出し元ノードの前に出現する場合にセットされます。これらの定数をビット論理積演算子&と組み合わせて使うことで、特定の条件が満たされているかを効率的に判定できます。

コードではまず簡単なXMLドキュメントを作成し、<first>要素と<second>要素の2つのDOMElementノードを取得しています。そして、firstノードから見てsecondノードの位置を比較しDOM_DOCUMENT_POSITION_FOLLOWINGの使用例を、次にsecondノードから見てfirstノードの位置を比較しDOM_DOCUMENT_POSITION_PRECEDINGの使用例をそれぞれ具体的に示しています。これにより、ドキュメント内のノードの相対的な位置をプログラムで正確に特定する手法を学べます。

Copy
1<?php
2
3/**
4 * 2つのDOMノードの位置関係を比較し、
5 * 特定のノードがもう一方のノードの後に位置するかどうかを判定します。
6 *
7 * この関数はDOMText::DOCUMENT_POSITION_FOLLOWING定数の使用例を示します。
8 * 比較結果はビットマスクで返され、この定数を使って特定のフラグがセットされているかを確認します。
9 *
10 * @param DOMNode $node1 比較対象の最初のノード。
11 * @param DOMNode $node2 比較対象の2番目のノード。
12 * @return string 比較結果の説明。
13 */
14function describeDomNodePosition(DOMNode $node1, DOMNode $node2): string
15{
16    // DOMNode::compareDocumentPosition() メソッドを使用してノードの位置を比較します。
17    // このメソッドは、2つのノード間の位置関係を示すビットマスクを返します。
18    // 例: DOMText::DOCUMENT_POSITION_FOLLOWING は、node2 が node1 の後に続くことを示します。
19    $position = $node1->compareDocumentPosition($node2);
20
21    $resultDescription = "";
22
23    // DOMText::DOCUMENT_POSITION_FOLLOWING は、node2 が node1 の「後」に続く場合に
24    // セットされるビットフラグです。
25    // ビット論理積 (&) を使って、このフラグがセットされているかを確認します。
26    if (($position & DOMText::DOCUMENT_POSITION_FOLLOWING) === DOMText::DOCUMENT_POSITION_FOLLOWING) {
27        $resultDescription = "ノード '{$node2->nodeName}' はノード '{$node1->nodeName}' の後に続きます。\n";
28    } elseif (($position & DOMText::DOCUMENT_POSITION_PRECEDING) === DOMText::DOCUMENT_POSITION_PRECEDING) {
29        $resultDescription = "ノード '{$node2->nodeName}' はノード '{$node1->nodeName}' の前に位置します。\n";
30    } elseif (($position & DOMText::DOCUMENT_POSITION_CONTAINS) === DOMText::DOCUMENT_POSITION_CONTAINS) {
31        $resultDescription = "ノード '{$node1->nodeName}' はノード '{$node2->nodeName}' を含みます。\n";
32    } elseif (($position & DOMText::DOCUMENT_POSITION_CONTAINED_BY) === DOMText::DOCUMENT_POSITION_CONTAINED_BY) {
33        $resultDescription = "ノード '{$node1->nodeName}' はノード '{$node2->nodeName}' に含まれます。\n";
34    } elseif ($position === 0) {
35        $resultDescription = "ノード '{$node1->nodeName}' とノード '{$node2->nodeName}' は同じノードです。\n";
36    } else {
37        $resultDescription = "ノード '{$node1->nodeName}' とノード '{$node2->nodeName}' の位置関係は不明です (ビットマスク: {$position})。\n";
38    }
39
40    return $resultDescription;
41}
42
43// --- サンプル実行 ---
44
45// 1. 新しいDOMドキュメントを作成します。
46$dom = new DOMDocument('1.0', 'UTF-8');
47$dom->formatOutput = true; // 出力を整形して見やすくします。
48
49// 2. DOMツリーを構築します。
50$root = $dom->createElement('root');
51$dom->appendChild($root);
52
53$elementA = $dom->createElement('elementA');
54$root->appendChild($elementA);
55
56$textNodeA = $dom->createTextNode('Text A'); // 最初のテキストノード
57$elementA->appendChild($textNodeA);
58
59$elementB = $dom->createElement('elementB');
60$root->appendChild($elementB);
61
62$textNodeB = $dom->createTextNode('Text B'); // 2番目のテキストノード
63$elementB->appendChild($textNodeB);
64
65// 構築されたDOMツリーのイメージ:
66// <root>
67//   <elementA>
68//     Text A (textNodeA)
69//   </elementA>
70//   <elementB>
71//     Text B (textNodeB)
72//   </elementB>
73// </root>
74
75echo "--- DOMツリーの構築とノード位置比較のデモンストレーション ---\n\n";
76echo "現在のDOMツリー:\n" . $dom->saveXML() . "\n";
77
78// 3. describeDomNodePosition 関数を使ってノード間の位置を比較し、結果を表示（post）します。
79
80echo "--- 比較結果 ---\n";
81
82// 例1: textNodeA と textNodeB の比較
83// textNodeB は textNodeA の後に続くはずです。
84echo describeDomNodePosition($textNodeA, $textNodeB);
85
86// 例2: elementA と elementB の比較
87// elementB は elementA の後に続くはずです。
88echo describeDomNodePosition($elementA, $elementB);
89
90// 例3: textNodeB と textNodeA の比較 (逆順)
91// textNodeA は textNodeB の前に位置するはずです。
92echo describeDomNodePosition($textNodeB, $textNodeA);
93
94// 例4: elementA と textNodeA の比較 (包含関係)
95// elementA は textNodeA を含むはずです。
96echo describeDomNodePosition($elementA, $textNodeA);
97
98// 例5: textNodeA と elementA の比較 (包含関係の逆)
99// textNodeA は elementA に含まれるはずです。
100echo describeDomNodePosition($textNodeA, $elementA);
101
102// 例6: 同じノードの比較
103// 同じノードは位置関係がない (0) となります。
104echo describeDomNodePosition($textNodeA, $textNodeA);
105
106?>

PHP 8におけるDOMText::DOCUMENT_POSITION_FOLLOWING定数は、DOMツリー内で2つのノード間の位置関係を比較する際に利用される、整数型のビットフラグです。この定数は、主にDOMNode::compareDocumentPosition()メソッドの戻り値を解釈するために用いられます。

compareDocumentPosition()メソッドは、比較対象のノードがもう一方のノードに対して「後に続く」「前に位置する」「含む」といった関係をビットマスクとして返します。DOMText::DOCUMENT_POSITION_FOLLOWINGは、比較対象の2番目のノードが最初のノードの「後に続く」という場合に、メソッドの戻り値に含まれるビットフラグの一つです。

サンプルコードのdescribeDomNodePosition関数は、この定数の使用例を示しています。この関数は2つのDOMNode型の引数を受け取り（コード内のphpdocで@paramとして説明されています）、compareDocumentPosition()の結果に対し、ビット論理積演算子&を用いてDOMText::DOCUMENT_POSITION_FOLLOWINGがセットされているかを確認します。これにより、ノードの具体的な位置関係を判定し、その説明を文字列として返します。サンプル実行部分では、実際のDOMツリーを構築し、異なるノード間で比較を行い、結果を出力（post）して定数の動作を分かりやすく示しています。この定数は、DOM操作においてノードの相対的な位置をプログラムで正確に判断するために不可欠です。