【PHP8.x】Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS定数の使い方

Copy
1<?php
2
3/**
4 * 2つのDOMノード間の位置関係を比較し、一方のノードがもう一方のノードを含むか確認します。
5 * Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS 定数を使用して、ノードの包含関係を判定します。
6 * システムエンジニアを目指す初心者がDOM操作と定数の利用を理解するのに役立ちます。
7 */
8function demonstrateDomNodePositionComparison(): void
9{
10    // 新しいDOMドキュメントを作成し、サンプルHTMLをロードします。
11    // このHTMLは、divがpを含み、pがspanを含む階層構造を持っています。
12    $dom = new DOMDocument();
13    $dom->loadHTML('<div><p><span>Hello World!</span></p></div>');
14
15    // 比較対象となるDOMノードを取得します。
16    // getElementsByTagNameはDOMNodeListを返すため、item(0)で最初の要素を取得します。
17    $nodeA = $dom->getElementsByTagName('div')->item(0); // 親ノードの例
18    $nodeB = $dom->getElementsByTagName('p')->item(0);  // 子ノードの例
19    $nodeC = $dom->getElementsByTagName('span')->item(0); // 孫ノードの例
20
21    // ノードが取得できなかった場合の簡単なエラーチェック
22    if (!$nodeA || !$nodeB || !$nodeC) {
23        echo "エラー: 必要なDOM要素が見つかりませんでした。\n";
24        return;
25    }
26
27    echo "--- DOMノードの位置比較のデモンストレーション ---\n\n";
28
29    // 例1: $nodeA (div) が $nodeB (p) を含んでいるかを確認します。
30    // compareDocumentPositionはビットマスクを返すため、ビット演算子 '&' を使用して特定の定数がセットされているかを確認します。
31    $positionAB = $nodeA->compareDocumentPosition($nodeB);
32    echo "1. \$nodeA (div) と \$nodeB (p) を比較:\n";
33    echo "   比較結果の生の値: " . $positionAB . "\n";
34    if (($positionAB & Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) === Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) {
35        echo "   -> 結果: \$nodeA (div) は \$nodeB (p) を含んでいます。\n"; // この条件が真になります
36    } else {
37        echo "   -> 結果: \$nodeA (div) は \$nodeB (p) を含んでいません。\n";
38    }
39    echo "\n";
40
41    // 例2: $nodeB (p) が $nodeA (div) を含んでいるかを確認します。（逆方向）
42    // この場合、$nodeBは$nodeAに「含まれる」ので、「含む」は偽になります。
43    $positionBA = $nodeB->compareDocumentPosition($nodeA);
44    echo "2. \$nodeB (p) と \$nodeA (div) を比較:\n";
45    echo "   比較結果の生の値: " . $positionBA . "\n";
46    if (($positionBA & Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) === Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) {
47        echo "   -> 結果: \$nodeB (p) は \$nodeA (div) を含んでいます。\n";
48    } else {
49        echo "   -> 結果: \$nodeB (p) は \$nodeA (div) を含んでいません。\n"; // この条件が真になります
50        // 参考: DOMNode::DOCUMENT_POSITION_CONTAINED_BY が真になります
51        if (($positionBA & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) === DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
52            echo "   (補足: \$nodeB (p) は \$nodeA (div) に含まれています。)\n";
53        }
54    }
55    echo "\n";
56
57    // 例3: $nodeA (div) が $nodeC (span) を含んでいるかを確認します。（孫ノード）
58    // DOMツリー上で直接の子でなくても、階層的に含んでいれば `CONTAINS` は真になります。
59    $positionAC = $nodeA->compareDocumentPosition($nodeC);
60    echo "3. \$nodeA (div) と \$nodeC (span) を比較:\n";
61    echo "   比較結果の生の値: " . $positionAC . "\n";
62    if (($positionAC & Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) === Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS) {
63        echo "   -> 結果: \$nodeA (div) は \$nodeC (span) を含んでいます。\n"; // この条件が真になります
64    } else {
65        echo "   -> 結果: \$nodeA (div) は \$nodeC (span) を含んでいません。\n";
66    }
67    echo "\n";
68}
69
70// デモンストレーション関数を実行します。
71demonstrateDomNodePositionComparison();

PHPのDOM操作において、Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINSは、二つのDOMノード間の位置関係を比較し、一方のノードがもう一方のノードを階層的に含んでいるかを判定するために使用される定数です。この定数自体は整数値（int）を返し、引数は取りません。主にDOMNodeクラスのcompareDocumentPosition()メソッドの戻り値と組み合わせて利用されます。

compareDocumentPosition()メソッドは、比較対象のノードとの位置関係を示すビットマスク形式の整数値を返します。この戻り値とDOCUMENT_POSITION_CONTAINS定数をビット論理AND演算子&で比較することで、基準となるノードが比較対象のノードを「含んでいる」状態であるかを確認できます。

サンプルコードでは、DOMDocumentにロードされたHTML内の<div>、<p>、<span>といったノードを取得し、それぞれの包含関係をデモンストレーションしています。例えば、divノードが子要素であるpノードや孫要素であるspanノードを祖先として含んでいる場合に、この定数との比較が真となります。これにより、ウェブページのDOM構造をプログラムで解析し、特定の要素が別の要素の内部に存在するかどうかを正確に判断することが可能になります。システムエンジニアを目指す初心者の方にとって、DOMツリーの探索や要素の関連性判定の理解に役立つでしょう。

Copy
1<?php
2
3use Dom\Document;
4use Dom\Element;
5
6/**
7 * 2つのDOMノード間の位置関係を比較し、最初のノードが2番目のノードを含んでいるかを確認します。
8 *
9 * この関数は `Dom\Node::compareDocumentPosition` メソッドを使用します。
10 * その戻り値はビットマスクであり、ノード間の様々な位置関係を示します。
11 *
12 * 特に、`Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS` 定数（実際には
13 * `Dom\Node` で定義されていますが、`Dom\ProcessingInstruction` クラスを通じて参照可能です）
14 * は、参照ノードが指定されたノードを含んでいる（つまり、参照ノードが指定されたノードの祖先である）
15 * ことを示すビットです。
16 *
17 * @param Dom\Node $ancestorCandidate 祖先ノードである可能性のあるノード。
18 * @param Dom\Node $descendantCandidate 子孫ノードである可能性のあるノード。
19 * @return bool `$ancestorCandidate` が `$descendantCandidate` を含んでいれば `true`、
20 *              そうでなければ `false` を返します。
21 */
22function isAncestorOf(Dom\Node $ancestorCandidate, Dom\Node $descendantCandidate): bool
23{
24    // compareDocumentPosition は、2つのノード間の相対的な位置関係を示すビットマスクを返します。
25    $position = $ancestorCandidate->compareDocumentPosition($descendantCandidate);
26
27    // 論理AND演算子 (&) を使用して、戻り値に DOCUMENT_POSITION_CONTAINS のビットが
28    // 含まれているかを確認します。
29    // Dom\ProcessingInstruction は Dom\Node を継承しているため、
30    // Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS 定数を参照できます。
31    return (bool) ($position & Dom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS);
32}
33
34// サンプルコードの実行例
35$document = new Document();
36$rootElement = $document->createElement('root');
37$document->appendChild($rootElement);
38
39$parentElement = $document->createElement('parent');
40$rootElement->appendChild($parentElement);
41
42$childElement = $document->createElement('child');
43$parentElement->appendChild($childElement);
44
45$siblingElement = $rootElement->createElement('sibling'); // rootElementの子だが、parentElementの子ではない
46$rootElement->appendChild($siblingElement);
47
48$unrelatedElement = $document->createElement('unrelated'); // ドキュメントツリーに属さないノード
49
50echo "ルート要素が親要素を含んでいますか？: "
51    . (isAncestorOf($rootElement, $parentElement) ? 'はい' : 'いいえ') . PHP_EOL;
52
53echo "親要素が子要素を含んでいますか？: "
54    . (isAncestorOf($parentElement, $childElement) ? 'はい' : 'いいえ') . PHP_EOL;
55
56echo "子要素が親要素を含んでいますか？: "
57    . (isAncestorOf($childElement, $parentElement) ? 'はい' : 'いいえ') . PHP_EOL; // 逆は含まない
58
59echo "親要素が兄弟要素を含んでいますか？: "
60    . (isAncestorOf($parentElement, $siblingElement) ? 'はい' : 'いいえ') . PHP_EOL; // 含まない
61
62echo "ルート要素が子要素を含んでいますか？: "
63    . (isAncestorOf($rootElement, $childElement) ? 'はい' : 'いいえ') . PHP_EOL; // 階層的に含む
64
65echo "親要素が無関係な要素を含んでいますか？: "
66    . (isAncestorOf($parentElement, $unrelatedElement) ? 'はい' : 'いいえ') . PHP_EOL; // 含まない
67
68?>

PHPのDom\ProcessingInstruction::DOCUMENT_POSITION_CONTAINS定数は、DOMツリー上にある2つのノード間の位置関係を判断するために利用される特別な値です。この定数は整数値で、特に「あるノードが別のノードを含んでいる（つまり、祖先である）」という関係性を示します。

サンプルコードのisAncestorOf関数は、この定数を利用して、渡された2つのDom\Nodeオブジェクトが祖先・子孫関係にあるかを判定します。この関数は、祖先である可能性のあるノードと子孫である可能性のあるノードをそれぞれ引数として受け取ります。関数内では、祖先候補ノードのcompareDocumentPositionメソッドが呼び出されます。このメソッドの戻り値は、ノード間の様々な位置関係を示すビットマスクという特別な整数値です。isAncestorOf関数は、このビットマスクとDOCUMENT_POSITION_CONTAINS定数を論理AND演算子&で比較します。この比較結果がtrueであれば、最初のノードが2番目のノードの祖先であると判断し、最終的にtrueを返します。そうでなければfalseを返します。

このように、DOCUMENT_POSITION_CONTAINS定数は、Dom\Node::compareDocumentPositionメソッドと組み合わせて、DOM要素の包含関係をプログラムで効率的に判定する際に非常に役立ちます。