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

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドと
5 * DOMNode::DOCUMENT_POSITION_PRECEDING 定数を使って、
6 * 2つのDOMノードの文書内の位置関係を比較するサンプル関数です。
7 *
8 * DOMNode::DOCUMENT_POSITION_PRECEDING は、比較対象のノードが
9 * 参照ノードよりも文書ツリー上で「先行している」場合に、
10 * compareDocumentPosition() メソッドの戻り値に含まれるビットマスクの定数です。
11 * （PHPのDOM拡張では、この定数はDOMNodeクラスに定義されています。）
12 */
13function demonstrateDocumentPositionPreceding(): void
14{
15    // 新しいDOMドキュメントを作成します
16    $dom = new DOMDocument();
17    $dom->preserveWhiteSpace = false; // 空白ノードを無視して整形しやすくします
18    $dom->formatOutput = true;      // 出力を整形します
19
20    // ルート要素を作成し、ドキュメントに追加します
21    $root = $dom->createElement('root');
22    $dom->appendChild($root);
23
24    // 子要素をいくつか作成し、文書ツリーを構築します
25    $child1 = $dom->createElement('child1');
26    $root->appendChild($child1);
27
28    $grandchild1 = $dom->createElement('grandchild1');
29    $child1->appendChild($grandchild1);
30
31    $child2 = $dom->createElement('child2');
32    $root->appendChild($child2);
33
34    $grandchild2 = $dom->createElement('grandchild2');
35    $child2->appendChild($grandchild2);
36    
37    echo "構築されたDOMツリー:\n";
38    echo $dom->saveXML();
39    echo "\n";
40
41    // 比較対象のノードを2つ取得します。
42    // $nodeA は $nodeB よりも文書上で先行しています。
43    $nodeA = $child1;
44    $nodeB = $child2;
45
46    echo "--- ケース1: ノードAがノードBに先行する場合 ---\n";
47    echo "ノードA ('{$nodeA->nodeName}') と ノードB ('{$nodeB->nodeName}') を比較します。\n";
48
49    // nodeA と nodeB の位置を比較します。
50    // 戻り値はビットマスクの整数値で、複数の位置関係を示すフラグを含みます。
51    $position = $nodeA->compareDocumentPosition($nodeB);
52
53    // DOMNode::DOCUMENT_POSITION_PRECEDING (int) は、
54    // 参照ノード ($nodeA) が比較対象ノード ($nodeB) に先行している場合に
55    // 戻り値のビットマスクに含まれる定数です。
56    echo "compareDocumentPosition() の戻り値 (10進数): {$position}\n";
57    echo "DOMNode::DOCUMENT_POSITION_PRECEDING (10進数): " . DOMNode::DOCUMENT_POSITION_PRECEDING . "\n";
58
59    // ビット論理AND演算子を使って、DOCUMENT_POSITION_PRECEDING フラグが
60    // 戻り値に含まれているかチェックします。
61    if (($position & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
62        echo "結果: ノードA ('{$nodeA->nodeName}') はノードB ('{$nodeB->nodeName}') に先行します。\n";
63    } else {
64        echo "結果: ノードA ('{$nodeA->nodeName}') はノードB ('{$nodeB->nodeName}') に先行しません。\n";
65    }
66    echo "\n";
67
68    // 逆のパターンも試します。
69    // $nodeC は $nodeD よりも文書上で後続しています。
70    $nodeC = $child2;
71    $nodeD = $child1;
72
73    echo "--- ケース2: ノードCがノードDに後続する場合 ---\n";
74    echo "ノードC ('{$nodeC->nodeName}') と ノードD ('{$nodeD->nodeName}') を比較します。\n";
75    $position2 = $nodeC->compareDocumentPosition($nodeD);
76
77    echo "compareDocumentPosition() の戻り値 (10進数): {$position2}\n";
78    echo "DOMNode::DOCUMENT_POSITION_PRECEDING (10進数): " . DOMNode::DOCUMENT_POSITION_PRECEDING . "\n";
79
80    if (($position2 & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
81        echo "結果: ノードC ('{$nodeC->nodeName}') はノードD ('{$nodeD->nodeName}') に先行します。\n";
82    } else {
83        echo "結果: ノードC ('{$nodeC->nodeName}') はノードD ('{$nodeD->nodeName}') に先行しません。\n";
84    }
85    echo "\n";
86    echo "補足: 2番目のケースでは、'{$nodeC->nodeName}' が '{$nodeD->nodeName}' に後続するため、"
87       . "DOCUMENT_POSITION_PRECEDING フラグは含まれません。\n";
88}
89
90// 関数を実行します。
91demonstrateDocumentPositionPreceding();

このPHPサンプルコードは、DOMNode::DOCUMENT_POSITION_PRECEDING 定数の使い方を、DOMツリーにおけるノードの位置比較を通して解説しています。この定数は、XMLやHTMLなどのDOM（Document Object Model）ツリー内で、あるノードが別のノードよりも文書上で先行している（物理的に前に位置している）かどうかを判断するために利用されます。

主に DOMNode::compareDocumentPosition() メソッドと組み合わせて使用されます。compareDocumentPosition() メソッドは、比較元のノードと、比較対象のノードの間にどのような関係があるかを示す整数値（ビットマスクと呼ばれる複数の情報を含む数値）を戻り値として返します。DOMNode::DOCUMENT_POSITION_PRECEDING はこのビットマスクに含まれる可能性のあるフラグの一つで、比較対象のノードが、基準となるノードよりも文書ツリーの順序で「先行している」場合に、戻り値にこの定数の値が含まれます。

サンプルコードでは、まずDOMツリーを作成し、2つのノード $child1 と $child2 を用意します。その後、$child1 (nodeA) を基準とし $child2 (nodeB) を比較対象として、$child1 が$child2 に先行しているかどうかを compareDocumentPosition() メソッドの戻り値と DOMNode::DOCUMENT_POSITION_PRECEDING 定数をビット論理AND演算子 (&) で組み合わせることで確認しています。この定数自体は引数を取らず、その値は整数です。このようにして、DOMツリー内のノード間の相対的な順序を正確に判断することができます。

Copy
1<?php
2
3/**
4 * 2つのDOMノードの相対的なドキュメント位置を比較し、
5 * 最初のノードが2番目のノードに先行しているかどうかを判定します。
6 *
7 * @param DOMNode $node1 比較対象の最初のノード。DOMElementまたはDOMAttrなどが含まれます。
8 * @param DOMNode $node2 比較対象の2番目のノード。DOMElementまたはDOMAttrなどが含まれます。
9 * @return string ノード1がノード2に先行している場合はその旨を示す文字列を、
10 *                それ以外の場合は先行していない旨を示す文字列を返します。
11 *                内部的には、比較後に取得されるビットマスクとDOMAttr::DOCUMENT_POSITION_PRECEDING定数を評価します。
12 *
13 * @phpdoc このドキュメントブロックは、PHPの標準的なドキュメントコメント（phpDoc）の例です。
14 *         コードの目的、引数、戻り値などを記述し、可読性と保守性を高めます。
15 *
16 * @post この関数は、ノードの位置比較（DOMNode::compareDocumentPosition() メソッド）を行った「後」の結果を評価します。
17 *       `DOMAttr::DOCUMENT_POSITION_PRECEDING` 定数は、比較後に得られるビットマスクの一部として利用されます。
18 *
19 * @param これは、PHPDocコメント内で関数やメソッドの引数を説明するために使用される`@param`タグの例です。
20 *        引数の型と変数名、そしてその説明を記述します。
21 */
22function checkNodePrecedence(DOMNode $node1, DOMNode $node2): string
23{
24    // DOMNode::compareDocumentPosition() メソッドを使用して、2つのノードのドキュメント内での相対位置を比較します。
25    // このメソッドは、複数の位置情報（例: 先行、後続、包含、属性など）を含むビットマスク (int値) を返します。
26    $position = $node1->compareDocumentPosition($node2);
27
28    // `DOMAttr::DOCUMENT_POSITION_PRECEDING` 定数とビット論理AND演算 (`&`) で比較します。
29    // この定数は、最初のノードが2番目のノードよりも前にドキュメントツリーに位置している場合に、
30    // compareDocumentPosition() の戻り値のビットマスクに含まれます。
31    // 結果がこの定数と完全に一致する場合、先行していると判断できます。
32    if (($position & DOMAttr::DOCUMENT_POSITION_PRECEDING) === DOMAttr::DOCUMENT_POSITION_PRECEDING) {
33        return "最初のノードは2番目のノードに先行しています。 (比較結果ビットマスク: {$position})";
34    } else {
35        return "最初のノードは2番目のノードに先行していません。 (比較結果ビットマスク: {$position})";
36    }
37}
38
39// サンプルHTMLドキュメントをロードします。
40$dom = new DOMDocument();
41// loadHTMLはHTML5に対応していないため、エラーが発生する場合があります。
42// 簡単な例では、エラー抑制演算子 `@` を使用して警告を表示しないようにできます。
43@$dom->loadHTML('
44    <html>
45    <body>
46        <div id="container">
47            <p id="first-paragraph" class="intro">最初の段落</p>
48            <span id="target-span" data-id="123">ターゲットスパン</span>
49            <p id="second-paragraph">2番目の段落</p>
50        </div>
51    </body>
52    </html>
53');
54
55// 比較対象となるDOMElementノードとDOMAttrノードを取得します。
56$firstParagraph = $dom->getElementById('first-paragraph');
57$targetSpan = $dom->getElementById('target-span');
58$secondParagraph = $dom->getElementById('second-paragraph');
59
60// DOMAttrクラスの定数リファレンスなので、DOMAttrオブジェクトを比較に含めます。
61// 例えば、`firstParagraph` 要素の `class` 属性を取得します。
62// DOMAttrオブジェクトはDOMNodeを継承しているため、compareDocumentPosition() の引数として使用できます。
63$classAttribute = $firstParagraph->attributes->getNamedItem('class');
64
65// 別の属性ノードも取得します。`targetSpan` 要素の `data-id` 属性です。
66$dataIdAttribute = $targetSpan->attributes->getNamedItem('data-id');
67
68
69// 様々なノードの組み合わせで `checkNodePrecedence` 関数をテストし、結果を表示します。
70
71echo "--- DOMノードの先行関係チェック ---" . PHP_EOL;
72
73// ケース1: 最初の段落 (`p#first-paragraph`) がターゲットスパン (`span#target-span`) に先行する場合
74echo "ケース1: '最初の段落' と 'ターゲットスパン'" . PHP_EOL;
75echo checkNodePrecedence($firstParagraph, $targetSpan) . PHP_EOL . PHP_EOL;
76
77// ケース2: ターゲットスパン (`span#target-span`) が最初の段落 (`p#first-paragraph`) に先行しない場合
78echo "ケース2: 'ターゲットスパン' と '最初の段落'" . PHP_EOL;
79echo checkNodePrecedence($targetSpan, $firstParagraph) . PHP_EOL . PHP_EOL;
80
81// ケース3: `firstParagraph` の `class` 属性 (`DOMAttr`) が `targetSpan` に先行する場合
82// 属性ノードはオーナー要素の一部ですが、ドキュメントツリー上での位置はオーナー要素の直後ではありません。
83// しかし、ツリー順ではオーナー要素が存在する場所を基準に比較されます。
84echo "ケース3: 'class属性' (pタグ) と 'ターゲットスパン'" . PHP_EOL;
85echo checkNodePrecedence($classAttribute, $targetSpan) . PHP_EOL . PHP_EOL;
86
87// ケース4: `targetSpan` の `data-id` 属性 (`DOMAttr`) が `firstParagraph` に先行しない場合
88echo "ケース4: 'data-id属性' (spanタグ) と '最初の段落'" . PHP_EOL;
89echo checkNodePrecedence($dataIdAttribute, $firstParagraph) . PHP_EOL . PHP_EOL;
90
91// ケース5: 同じノード同士を比較した場合 (先行はしません)
92echo "ケース5: '最初の段落' と '最初の段落' (自身を比較)" . PHP_EOL;
93echo checkNodePrecedence($firstParagraph, $firstParagraph) . PHP_EOL . PHP_EOL;
94
95// ケース6: 属性ノード同士の比較 (`class` 属性 vs `data-id` 属性)
96echo "ケース6: 'class属性' (pタグ) と 'data-id属性' (spanタグ)" . PHP_EOL;
97echo checkNodePrecedence($classAttribute, $dataIdAttribute) . PHP_EOL . PHP_EOL;
98
99?>

このPHPコードは、HTMLドキュメントの構造を表すDOM（Document Object Model）ツリー内で、2つのノードの相対的な位置関係を比較する方法を示しています。特に、DOMAttrクラスのDOCUMENT_POSITION_PRECEDING定数を利用して、あるノードが別のノードよりもドキュメントツリー上で「先行しているか」を判定する機能を提供しています。

checkNodePrecedence関数は、比較対象となる2つのDOMNodeオブジェクト（$node1と$node2）を引数として受け取ります。この関数は、内部で$node1のcompareDocumentPosition()メソッドを呼び出し、$node2との相対位置を示すビットマスク（整数値）を取得します。その後、取得したビットマスクとDOMAttr::DOCUMENT_POSITION_PRECEDING定数をビット論理AND演算子で比較することで、$node1が$node2に先行しているかどうかを判断し、その結果を示す文字列を戻り値として返します。DOCUMENT_POSITION_PRECEDINGは、最初のノードが2番目のノードより前に位置していることを示すビットマスクの一部です。

サンプルコードでは、簡単なHTMLドキュメントを読み込み、複数のDOMElementノードやDOMAttrノードを取得しています。これらのノードを様々な組み合わせでcheckNodePrecedence関数に渡し、それぞれのノード間の先行関係がどのように判定されるかを具体的な実行結果で示しています。これにより、DOMノードの比較機能とDOCUMENT_POSITION_PRECEDING定数の使われ方を実践的に理解できます。