【PHP8.x】DOMNotation::DOCUMENT_POSITION_PRECEDING定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::DOCUMENT_POSITION_PRECEDING 定数の使用例。
5 *
6 * この定数は、DOMツリー内の2つのノードの相対的な位置を比較する際に使用され、
7 * 比較対象のノードが参照ノードよりもDOMツリー上で物理的に前に位置することを示します。
8 * DOMNode::compareDocumentPosition() メソッドの戻り値はビットマスクであり、
9 * この定数とビット論理AND演算子 (&) を使って特定の状態をチェックします。
10 */
11function demonstrateDocumentPositionPrecedingConstant(): void
12{
13    // 新しいDOMDocumentオブジェクトを作成
14    $dom = new DOMDocument();
15    // サンプルXMLをロード
16    $dom->loadXML('<root><elementA/><elementB/><elementC/></root>');
17
18    // 比較に使用するノードを取得
19    // elementA は elementB の前に位置する
20    $elementA = $dom->getElementsByTagName('elementA')->item(0);
21    $elementB = $dom->getElementsByTagName('elementB')->item(0);
22
23    // ノードが正しく取得できたか確認
24    if ($elementA === null || $elementB === null) {
25        echo "エラー: 必要なDOMノードが見つかりませんでした。\n";
26        return;
27    }
28
29    echo "--- DOMノードの位置関係の比較 ---\n\n";
30
31    // elementB (参照ノード) から見て elementA (比較対象ノード) の位置を比較
32    // elementA は elementB の「前」に位置するため、DOCUMENT_POSITION_PRECEDING のフラグが立ちます。
33    $positionResult = $elementB->compareDocumentPosition($elementA);
34
35    echo "参照ノード: elementB\n";
36    echo "比較対象ノード: elementA\n";
37    echo "compareDocumentPosition() の結果 (ビットマスク値): " . $positionResult . "\n";
38    echo "DOMNode::DOCUMENT_POSITION_PRECEDING の値: " . DOMNode::DOCUMENT_POSITION_PRECEDING . "\n\n";
39
40    // 結果に DOMNode::DOCUMENT_POSITION_PRECEDING が含まれているかチェック
41    if ($positionResult & DOMNode::DOCUMENT_POSITION_PRECEDING) {
42        echo "✅ 結果には DOCUMENT_POSITION_PRECEDING が含まれています。\n";
43        echo "   つまり、elementA は elementB の物理的に前に位置しています。\n";
44    } else {
45        echo "❌ 結果には DOCUMENT_POSITION_PRECEDING が含まれていません。\n";
46    }
47
48    echo "\n-----------------------------------\n\n";
49
50    // 別の比較例: elementA (参照ノード) から見て elementB (比較対象ノード) の位置を比較
51    // elementB は elementA の「後」に位置するため、DOCUMENT_POSITION_PRECEDING のフラグは立ちません。
52    $positionResultInverse = $elementA->compareDocumentPosition($elementB);
53
54    echo "参照ノード: elementA\n";
55    echo "比較対象ノード: elementB\n";
56    echo "compareDocumentPosition() の結果 (ビットマスク値): " . $positionResultInverse . "\n\n";
57
58    // 結果に DOMNode::DOCUMENT_POSITION_PRECEDING が含まれているかチェック
59    if ($positionResultInverse & DOMNode::DOCUMENT_POSITION_PRECEDING) {
60        echo "❌ 結果には DOCUMENT_POSITION_PRECEDING が含まれています。\n";
61    } else {
62        echo "✅ 結果には DOCUMENT_POSITION_PRECEDING が含まれていません。\n";
63        echo "   つまり、elementB は elementA の物理的に後に位置しています。\n";
64    }
65}
66
67// 関数を実行して定数の動作を確認
68demonstrateDocumentPositionPrecedingConstant();
69

PHP 8のDOMNode::DOCUMENT_POSITION_PRECEDING定数は、XMLやHTMLなどのDOMツリーにおいて、二つのノード間の相対的な位置関係を比較する際に使用される整数値です。この定数自体に引数はなく、その値は整数型です。

この定数の主な役割は、比較対象のノードが参照ノードよりもDOMツリー上で物理的に「前に位置している」状態を示すフラグとして機能することです。具体的には、DOMNode::compareDocumentPosition()メソッドの戻り値と組み合わせて使用されます。compareDocumentPosition()メソッドは、二つのノードのさまざまな位置関係をビットマスク（複数の情報をまとめた整数値）として返します。

その戻り値に対し、ビット論理AND演算子（&）とDOMNode::DOCUMENT_POSITION_PRECEDING定数を使用することで、比較対象ノードが参照ノードよりも前に存在するかどうかを正確に判別できます。サンプルコードでは、XML文書のelementAとelementBを例に挙げています。elementBから見てelementAの位置を比較し、その結果にこの定数の値が含まれていれば、elementAはelementBよりも前に位置すると判断できるのです。このように、文書構造におけるノードの順序をプログラムで確認する際に役立つ定数です。

Copy
1<?php
2
3/**
4 * 2つのDOMノードを比較し、最初のノードが2番目のノードより文書ツリーで前に位置するかどうかを判定します。
5 *
6 * DOMNode::compareDocumentPosition() メソッドは、2つのノード間の位置関係を示すビットマスクを返します。
7 * DOMNode::DOCUMENT_POSITION_PRECEDING は、比較対象のノードが参照ノードより文書ツリーで物理的に
8 * 前に位置することを示すビットフラグです。
9 * この関数は、XML/HTML文書ツリーにおけるノードの相対的な順序を理解するのに役立ちます。
10 *
11 * @param DOMNode $nodeA 比較する最初のDOMノード。
12 * @param DOMNode $nodeB 比較する2番目のDOMノード（参照ノード）。
13 * @return bool $nodeA が $nodeB より文書ツリーで前に位置する場合に true、それ以外は false を返します。
14 */
15function isNodePrecedingInDocument(DOMNode $nodeA, DOMNode $nodeB): bool
16{
17    // compareDocumentPosition はビットマスクを返すため、ビットAND演算子 (&) を使って特定の定数と比較します。
18    // DOMNode::DOCUMENT_POSITION_PRECEDING は、DOMNode クラスの定数です。
19    // 戻り値がこの定数を含む場合、nodeA は nodeB より前に位置します。
20    return (bool)($nodeA->compareDocumentPosition($nodeB) & DOMNode::DOCUMENT_POSITION_PRECEDING);
21}
22
23// --- 単体で動作可能なサンプルコード ---
24
25// 1. 新しいDOMDocumentオブジェクトを作成
26$dom = new DOMDocument('1.0', 'UTF-8');
27// 出力を整形するため、formatOutputをtrueに設定
28$dom->formatOutput = true;
29
30// 2. XML文字列を読み込み、DOMツリーを構築
31$xmlString = '<root><item id="first"/><item id="second"/><item id="third"/></root>';
32if (!$dom->loadXML($xmlString)) {
33    echo "XMLの読み込みに失敗しました。" . PHP_EOL;
34    exit(1);
35}
36
37// 3. 比較対象となるDOMノードを取得
38// getElementsByTagName を使用して、<item>要素のDOMNodeListを取得
39$items = $dom->getElementsByTagName('item');
40
41// 各ノードを取得。DOMNodeListは0から始まるインデックスでアクセス
42$firstItem = $items->item(0);  // <item id="first"/>
43$secondItem = $items->item(1); // <item id="second"/>
44$thirdItem = $items->item(2);  // <item id="third"/>
45
46// ノードが正しく取得できたか確認
47if ($firstItem && $secondItem && $thirdItem) {
48    echo "--- DOMノード位置の比較結果 ---" . PHP_EOL;
49
50    // 例1: firstItem は secondItem より前に位置するか？ -> 期待値: true
51    $result1 = isNodePrecedingInDocument($firstItem, $secondItem);
52    echo "firstItem は secondItem より前に位置する: " . ($result1 ? 'はい' : 'いいえ') . PHP_EOL;
53
54    // 例2: secondItem は firstItem より前に位置するか？ -> 期待値: false
55    $result2 = isNodePrecedingInDocument($secondItem, $firstItem);
56    echo "secondItem は firstItem より前に位置する: " . ($result2 ? 'はい' : 'いいえ') . PHP_EOL;
57
58    // 例3: thirdItem は secondItem より前に位置するか？ -> 期待値: false
59    $result3 = isNodePrecedingInDocument($thirdItem, $secondItem);
60    echo "thirdItem は secondItem より前に位置する: " . ($result3 ? 'はい' : 'いいえ') . PHP_EOL;
61
62    // 例4: secondItem は thirdItem より前に位置するか？ -> 期待値: true
63    $result4 = isNodePrecedingInDocument($secondItem, $thirdItem);
64    echo "secondItem は thirdItem より前に位置する: " . ($result4 ? 'はい' : 'いいえ') . PHP_EOL;
65} else {
66    echo "必要なDOMノードが見つかりませんでした。XML構造または取得処理を確認してください。" . PHP_EOL;
67}

このPHPコードは、XMLやHTMLなどのDOM文書を扱う際に、2つのDOMノードが文書ツリー上でどちらが物理的に前に位置するかを判定する方法を示しています。

核となるのはDOMNode::compareDocumentPosition()メソッドとDOMNode::DOCUMENT_POSITION_PRECEDING定数です。compareDocumentPosition()メソッドは、比較対象のノードと参照ノード間の関係を示す整数値（ビットマスク）を返します。この戻り値には、参照ノードより物理的に前に位置する場合に設定されるDOCUMENT_POSITION_PRECEDINGというビットフラグが含まれることがあります。

サンプルコードのisNodePrecedingInDocument関数は、2つのDOMNodeオブジェクト$nodeAと$nodeBを引数に取ります。この関数は、$nodeAが$nodeBより文書ツリーで前に位置するかどうかを判定し、その結果を真偽値（trueまたはfalse）で返します。具体的な判定は、$nodeA->compareDocumentPosition($nodeB)の戻り値とDOMNode::DOCUMENT_POSITION_PRECEDING定数をビットAND演算子&で比較することで行われます。ビットAND演算は、戻り値にDOCUMENT_POSITION_PRECEDINGフラグが含まれているかを効率的に確認するために使用されます。

コードの後半では、実際にXML文字列からDOMツリーを構築し、異なる位置にある複数の<item>ノードを取得しています。そして、これらのノードペアに対してisNodePrecedingInDocument関数を適用し、文書ツリーにおけるノードの相対的な順序がどのように判定されるかを具体的に出力して確認しています。これにより、DOMノード間の前後関係をプログラムから正確に把握できることがわかります。