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

Copy
1<?php
2
3// DOMDocument と DOMNode を使用して、HTMLドキュメント内のノード間の位置関係を比較するサンプルコードです。
4// Dom\DocumentFragment::DOCUMENT_POSITION_CONTAINS 定数を利用し、
5// あるノードが別のノードを含んでいるかどうかを判定する方法を示します。
6
7/**
8 * 指定されたHTMLから2つのノードを抽出し、最初のノードが2番目のノードを含んでいるかを確認します。
9 *
10 * @param string $html HTML文字列。DOMDocumentにロードされます。
11 * @param string $nodeXPath1 比較する最初のノード（親となる可能性のあるノード）を取得するためのXPath。
12 * @param string $nodeXPath2 比較する2番目のノード（子となる可能性のあるノード）を取得するためのXPath。
13 * @return void
14 */
15function demonstrateDocumentPositionContains(string $html, string $nodeXPath1, string $nodeXPath2): void
16{
17    // 新しいDOMDocumentオブジェクトを作成し、提供されたHTMLコンテンツをロードします。
18    // @ を使用して、HTMLの解析中に発生する可能性のある警告（例: 不完全なHTML）を抑制しています。
19    $dom = new DOMDocument();
20    @$dom->loadHTML($html);
21
22    // DOMXPathオブジェクトを作成し、XPathクエリを使用してノードを検索できるようにします。
23    $xpath = new DOMXPath($dom);
24
25    // XPathクエリを実行して、最初のノードと2番目のノードを取得します。
26    // ->item(0) は、クエリ結果（DOMNodeList）の最初の要素を取得します。
27    $node1 = $xpath->query($nodeXPath1)->item(0);
28    $node2 = $xpath->query($nodeXPath2)->item(0);
29
30    // どちらかのノードが見つからない場合は、エラーメッセージを表示して関数を終了します。
31    if (!$node1 || !$node2) {
32        echo "エラー: 指定されたXPath ('{$nodeXPath1}' または '{$nodeXPath2}') でノードが見つかりませんでした。\n\n";
33        return;
34    }
35
36    echo "比較対象ノード:\n";
37    // ノードのタグ名と、テキストコンテンツの冒頭を表示して、どのノードが比較されているかを示します。
38    echo "  ノード1 (親候補): <" . $node1->nodeName . "> (テキスト: '" . substr($node1->textContent, 0, 30) . "...')\n";
39    echo "  ノード2 (子候補): <" . $node2->nodeName . "> (テキスト: '" . substr($node2->textContent, 0, 30) . "...')\n";
40
41    // DOMNode::compareDocumentPosition() メソッドは、2つのノード間の位置関係を示すビットマスクを返します。
42    // 例: 親子関係、兄弟関係、異なるドキュメント、など。
43    // 詳細: https://www.php.net/manual/ja/domnode.comparedocumentposition.php
44    $position = $node1->compareDocumentPosition($node2);
45
46    // Dom\DocumentFragment::DOCUMENT_POSITION_CONTAINS 定数は、
47    // 参照ノード ($node1) が他のノード ($node2) を含んでいることを示す特定のビットフラグ（整数値）です。
48    // 返された $position の値とこの定数をビットAND演算子 (&) で比較することで、
49    // 参照ノードが他のノードを含んでいるかどうかを正確に判定できます。
50    if (($position & Dom\DocumentFragment::DOCUMENT_POSITION_CONTAINS) === Dom\DocumentFragment::DOCUMENT_POSITION_CONTAINS) {
51        echo "結果: ノード1 (<" . $node1->nodeName . ">) はノード2 (<" . $node2->nodeName . ">) を含んでいます。\n\n";
52    } else {
53        echo "結果: ノード1 (<" . $node1->nodeName . ">) はノード2 (<" . $node2->nodeName . ">) を含んでいません。\n\n";
54    }
55}
56
57// --- サンプルコードの実行例 ---
58
59// 例1: 親ノードが子ノードを「含んでいる」ケース
60echo "--- 実行例1: 親ノードが子ノードを含むケース ---\n";
61$htmlContent1 = '<div><p><span>Hello World!</span> This is a paragraph.</p></div>';
62demonstrateDocumentPositionContains($htmlContent1, '/html/body/div', '/html/body/div/p/span');
63
64// 例2: 親ノードが子ノードを「含んでいない」ケース（兄弟ノードの比較）
65echo "--- 実行例2: 親ノードが子ノードを含まないケース（兄弟ノード） ---\n";
66$htmlContent2 = '<div><p>First Paragraph</p><p>Second Paragraph</p></div>';
67demonstrateDocumentPositionContains($htmlContent2, '/html/body/div/p[1]', '/html/body/div/p[2]');
68
69// 例3: 親ノードが子ノードを「含んでいない」ケース（逆の階層関係）
70echo "--- 実行例3: 親ノードが子ノードを含まないケース（逆の階層関係） ---\n";
71$htmlContent3 = '<div><p>Another paragraph with <span>a span</span> inside.</p></div>';
72demonstrateDocumentPositionContains($htmlContent3, '/html/body/div/p/span', '/html/body/div');
73
74// 例4: 指定されたXPathでノードが「見つからない」ケース
75echo "--- 実行例4: 指定されたXPathでノードが見つからないケース ---\n";
76$htmlContent4 = '<div><p>A simple paragraph.</p></div>';
77demonstrateDocumentPositionContains($htmlContent4, '/html/body/div/span', '/html/body/div/p');
78
79?>

このPHPサンプルコードは、HTMLドキュメント内のノードが他のノードを含んでいるかどうかを判定する方法を示しています。具体的には、DOMDocumentクラスを使用してHTMLコンテンツをロードし、DOMXPathでXPathクエリを使って比較対象のノードを2つ取得します。

主要な処理は、DOMNodeオブジェクトのcompareDocumentPosition()メソッドにあります。このメソッドは、呼び出し元のノードともう一方のノードとの相対的な位置関係を示す整数値（ビットマスク）を返します。この整数値には、ノード間の親子関係や兄弟関係、別のドキュメントに属するかどうかといった情報が含まれます。

ここで利用されるDom\DocumentFragment::DOCUMENT_POSITION_CONTAINS定数は、参照ノードが他のノードを内包している状態を示す特定のビットフラグ（整数値）です。サンプルコードでは、compareDocumentPosition()メソッドが返した結果とこの定数をビットAND演算子 (&) で比較することで、最初のノードが2番目のノードを実際に含んでいるかどうかを正確に判定し、その結果を出力しています。

このコードはdemonstrateDocumentPositionContains関数として定義されており、引数として検証したいHTML文字列と、比較対象となる2つのノードを特定するためのXPath文字列を受け取ります。この関数自体には戻り値がなく（void）、判定結果を直接標準出力に表示する形で動作します。

Copy
1<?php
2
3/**
4 * DOMノードの包含関係を示す定数 Dom\Node::DOM_NODE_CONTAINS の使用例です。
5 * この定数は、Dom\Node::compareDocumentPosition() メソッドの戻り値を評価する際に利用され、
6 * あるノードが別のノードを含んでいるかどうかを判定します。
7 *
8 * PHP 8のDOM拡張において、Dom\DocumentFragmentクラス自体は compareDocumentPosition メソッドを持たず、
9 * DOCUMENT_POSITION_CONTAINS という定数も直接定義されていません。
10 * 代わりに Dom\Node クラスに定義されている DOM_NODE_CONTAINS 定数を使用し、
11 * ノード間の包含関係を比較します。Dom\DocumentFragment はノードを一時的に保持するコンテナとして使用します。
12 *
13 * @return void
14 */
15function demonstrateDomNodeContainsConstant(): void
16{
17    // 新しいDOMドキュメントを作成
18    $dom = new Dom\Document();
19
20    // ルート要素（親ノード）を作成し、ドキュメントに追加
21    $parentNode = $dom->createElement('div');
22    $parentNode->setAttribute('id', 'parent-container');
23    $dom->appendChild($parentNode);
24
25    // 子要素（子ノード）を作成し、親ノードに追加
26    $childNode = $dom->createElement('p', 'This is a child paragraph.');
27    $parentNode->appendChild($childNode);
28
29    // Dom\DocumentFragment を作成し、ノードを追加する例
30    // DocumentFragment は、複数のノードを一度にDOMに挿入するための軽量なコンテナです。
31    // それ自体はDOMツリーの通常のノードとして振る舞わず、compareDocumentPosition メソッドを持ちません。
32    $fragment = $dom->createDocumentFragment();
33    $fragment->appendChild($dom->createElement('span', 'Content within a fragment.'));
34    // 例として fragment の内容を親ノードに追加することも可能
35    // $parentNode->appendChild($fragment); // fragment の子ノードが parentNode に移動します
36
37    echo "--- DOM Node Position Comparison ---\n";
38
39    // 親ノードが子ノードを含んでいるかを比較
40    // compareDocumentPosition は Dom\Node クラスのメソッドです
41    $position = $parentNode->compareDocumentPosition($childNode);
42
43    echo "Comparing 'parentNode' and 'childNode':\n";
44
45    // Dom\Node::DOM_NODE_CONTAINS 定数を用いて、包含関係をチェックします。
46    // compareDocumentPosition の戻り値はビットマスクであるため、ビット論理AND演算子 (&) を使用します。
47    if (($position & Dom\Node::DOM_NODE_CONTAINS) === Dom\Node::DOM_NODE_CONTAINS) {
48        echo "  'parentNode' contains 'childNode'.\n";
49    } else {
50        echo "  'parentNode' does NOT contain 'childNode'.\n";
51    }
52
53    // 逆に子ノードが親ノードを含んでいるかを比較
54    $positionReverse = $childNode->compareDocumentPosition($parentNode);
55    echo "\nComparing 'childNode' and 'parentNode':\n";
56
57    if (($positionReverse & Dom\Node::DOM_NODE_CONTAINS) === Dom\Node::DOM_NODE_CONTAINS) {
58        echo "  'childNode' contains 'parentNode'. (これは通常のDOM構造では発生しません)\n";
59    } else {
60        echo "  'childNode' does NOT contain 'parentNode'. (想定される結果です)\n";
61    }
62
63    // 子ノードが親ノードに「含まれている」かを直接チェックする定数も存在します
64    if (($positionReverse & Dom\Node::DOM_NODE_IS_CONTAINED_BY) === Dom\Node::DOM_NODE_IS_CONTAINED_BY) {
65        echo "  'childNode' is contained by 'parentNode'. (これは想定される結果です)\n";
66    } else {
67        echo "  'childNode' is NOT contained by 'parentNode'.\n";
68    }
69}
70
71// 関数を実行してサンプルコードの動作を確認
72demonstrateDomNodeContainsConstant();

このサンプルコードは、PHPのDOM拡張機能を利用して、XMLやHTMLドキュメント内のノード間における包含関係を判定する方法を示しています。具体的には、Dom\Node::DOM_NODE_CONTAINS 定数を利用し、あるノードが別のノードを含んでいるかどうかを検証します。この定数は、Dom\Node::compareDocumentPosition() メソッドの戻り値を評価する際に使用されます。

Dom\Node::compareDocumentPosition() メソッドは、呼び出し元のノードと引数で指定されたノードとの位置関係を数値（ビットマスク）で返します。DOM_NODE_CONTAINS 定数（戻り値の型はint）は、このビットマスクに含まれる特定の情報、すなわち呼び出し元のノードが引数のノードを含んでいるかを示すフラグを抽出するために使われます。サンプルコードでは、親ノードが子ノードを含む場合にこの定数とビット論理AND演算子 (&) を使って真偽を判定しています。

リファレンス情報では Dom\DocumentFragment クラスの定数として記載されていますが、PHP 8のDOM拡張では、実際には Dom\Node クラスで定義されている DOM_NODE_CONTAINS 定数を使用します。Dom\DocumentFragment は複数のノードを一時的に保持するための軽量なコンテナであり、それ自体は直接 compareDocumentPosition メソッドや関連する定数を持たないため、サンプルのようにDOMドキュメントと通常のノードを作成して比較を行います。この方法により、DOMツリー内でのノードの親子関係や包含関係をプログラム的に正確に判断できるようになります。