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

Copy
1<?php
2
3// PHP 8 で導入された DOM 拡張の名前空間を使用します。
4// Dom\XMLDocument は DOMDocument の新しい名前空間エイリアスです。
5use Dom\XMLDocument;
6use Dom\Element;
7use Dom\Node; // compareDocumentPosition メソッドは Dom\Node クラスに定義されています。
8
9/**
10 * DOMノードの包含関係を比較するサンプルコード。
11 *
12 * Dom\XMLDocument::DOCUMENT_POSITION_CONTAINS 定数を使用して、
13 * あるノードが別のノードを含んでいるかを判断する方法を示します。
14 * この定数は、Dom\Node::compareDocumentPosition() メソッドの結果を
15 * ビットAND演算子 (`&`) でチェックする際に利用されます。
16 */
17function compareDomNodePositions(): void
18{
19    // 新しい XML ドキュメントを作成します。
20    $doc = new XMLDocument();
21    // ドキュメントのフォーマットを整える設定を有効にします。
22    $doc->formatOutput = true;
23
24    // XML ドキュメント内に DOM ツリーを構築します。
25    // <root> 要素を作成し、ドキュメントのルートに追加します。
26    $rootElement = $doc->createElement('root');
27    $doc->appendChild($rootElement);
28
29    // <child> 要素を作成し、<root> の子として追加します。
30    $childElement = $doc->createElement('child');
31    $rootElement->appendChild($childElement);
32
33    // <grandchild> 要素を作成し、<child> の子として追加します。
34    $grandchildElement = $doc->createElement('grandchild');
35    $childElement->appendChild($grandchildElement);
36
37    echo "--- 構築されたDOMツリーの構造 ---\n";
38    // saveXML() メソッドでドキュメント全体を文字列として出力します。
39    echo $doc->saveXML();
40    echo "\n";
41
42    echo "--- ノードの位置関係の比較 ---\n";
43
44    // 例1: rootElement が childElement を含んでいるか？
45    // $rootElement->compareDocumentPosition($childElement) は、
46    // $childElement から見た $rootElement の位置関係を示すビットマスクを返します。
47    // $rootElement は $childElement を含んでいるため、結果には DOCUMENT_POSITION_CONTAINS が含まれます。
48    $positionResult1 = $rootElement->compareDocumentPosition($childElement);
49
50    echo "1. rootElement と childElement の比較:\n";
51    // 結果が DOCUMENT_POSITION_CONTAINS 定数とビットAND演算で一致するか確認します。
52    // ビットAND演算 (&) は、複数の状態が同時に発生しうる定数（ビットマスク）をチェックする際に使用します。
53    if (($positionResult1 & XMLDocument::DOCUMENT_POSITION_CONTAINS) === XMLDocument::DOCUMENT_POSITION_CONTAINS) {
54        echo "  -> 結果: rootElement は childElement を含んでいます。\n";
55    } else {
56        echo "  -> 結果: rootElement は childElement を含んでいません。\n";
57    }
58    echo "\n";
59
60    // 例2: childElement が rootElement を含んでいるか？ (逆のケース)
61    // $childElement は $rootElement を含んでいません。
62    // この場合、$rootElement は $childElement の親なので、compareDocumentPosition の結果には
63    // DOCUMENT_POSITION_CONTAINS は含まれません (DOCUMENT_POSITION_CONTAINED_BY が含まれます)。
64    $positionResult2 = $childElement->compareDocumentPosition($rootElement);
65
66    echo "2. childElement と rootElement の比較:\n";
67    if (($positionResult2 & XMLDocument::DOCUMENT_POSITION_CONTAINS) === XMLDocument::DOCUMENT_POSITION_CONTAINS) {
68        echo "  -> 結果: childElement は rootElement を含んでいます。\n";
69    } else {
70        echo "  -> 結果: childElement は rootElement を含んでいません。\n";
71    }
72    echo "\n";
73
74    // 例3: childElement が grandchildElement を含んでいるか？
75    // $childElement は $grandchildElement を含んでいます。
76    $positionResult3 = $childElement->compareDocumentPosition($grandchildElement);
77
78    echo "3. childElement と grandchildElement の比較:\n";
79    if (($positionResult3 & XMLDocument::DOCUMENT_POSITION_CONTAINS) === XMLDocument::DOCUMENT_POSITION_CONTAINS) {
80        echo "  -> 結果: childElement は grandchildElement を含んでいます。\n";
81    } else {
82        echo "  -> 結果: childElement は grandchildElement を含んでいません。\n";
83    }
84    echo "\n";
85}
86
87// 定義した関数を実行し、DOMノードの包含関係を確認します。
88compareDomNodePositions();
89
90?>

Dom\XMLDocument::DOCUMENT_POSITION_CONTAINS 定数は、PHP 8で導入されたDOM（Document Object Model）拡張において、DOMツリー内のノード間の位置関係を示す際に使用されます。この定数自体には引数や戻り値はありませんが、特定のノードが別のノードを含んでいる状態、つまり親ノードが子ノードを内包していることを識別する整数値を提供します。

サンプルコードでは、XMLドキュメントを構築し、Dom\Node::compareDocumentPosition() メソッドを用いて複数のノード間の位置を比較しています。このメソッドは、比較対象のノードに対する呼び出し元ノードの位置関係を示すビットマスク（複数の状態をビットで表現した整数値）を戻り値として返します。

DOCUMENT_POSITION_CONTAINS 定数は、この compareDocumentPosition() メソッドの戻り値が持つ情報の一部を解釈するために利用されます。具体的には、戻り値と DOCUMENT_POSITION_CONTAINS 定数をビットAND演算子 (&) で比較し、結果が定数と一致する場合、呼び出し元ノードが比較対象ノードを含んでいると判断できます。例えば、親要素が子要素を含んでいるかを簡単に確認できるため、XMLやHTMLなどの文書構造をプログラムで操作する際のノード間の包含関係の判定に役立ち、システム開発におけるDOM操作の基礎知識として重要です。

Copy
1<?php
2
3/**
4 * リファレンス情報に基づいた Dom\XMLDocument クラスの模擬。
5 *
6 * PHP 8.0/8.1では、標準で `Dom\XMLDocument` クラスは提供されていません。
7 * このクラスは、リファレンス情報で指定された定数
8 * `DOCUMENT_POSITION_CONTAINS` をPHPDocコメント付きで示すためだけに存在します。
9 * 実際のDOM操作では、PHP標準の `DOMDocument` クラスを使用します。
10 * (PHP 8.2以降では、`Dom` 名前空間にDOM関連クラスが導入される予定です。)
11 */
12class Dom_XMLDocument_Simulated
13{
14    /**
15     * @const int DOCUMENT_POSITION_CONTAINS
16     * あるノードが別のノードを含んでいることを示すビットマスク定数。
17     *
18     * この定数は、DOMNode::compareDocumentPosition() メソッドの戻り値と
19     * ビット演算子 (`&`) を使って比較するために使用されます。
20     * 値はDOM Level 3 Core仕様に基づき `8` (または `0x08`) です。
21     * このビットがセットされている場合、比較対象のノード（例: `$node1->compareDocumentPosition($node2)` の `$node1`）が、
22     * もう一方のノード（`$node2`）を直接的または間接的に含んでいることを意味します。
23     */
24    public const DOCUMENT_POSITION_CONTAINS = 8;
25}
26
27/**
28 * DOMノード間の位置関係を比較し、`DOCUMENT_POSITION_CONTAINS` 定数を用いて解釈する関数。
29 *
30 * この関数は、PHPのDOM拡張におけるノードの位置関係の比較方法を、
31 * `Dom_XMLDocument_Simulated::DOCUMENT_POSITION_CONTAINS` 定数を例に説明します。
32 *
33 * @param \DOMNode $node1 比較する最初のノード（基準ノード）
34 * @param \DOMNode $node2 比較する2番目のノード
35 * @return void
36 */
37function demonstrateDocumentPositionContains(DOMNode $node1, DOMNode $node2): void
38{
39    // DOMNode::compareDocumentPosition() は、2つのノード間の位置関係を数値（ビットマスク）で返します。
40    // 返される数値は、複数の位置関係を表すビットが組み合わさったものです。
41    $position = $node1->compareDocumentPosition($node2);
42
43    echo "--- ノード位置の比較 ---" . PHP_EOL;
44    echo "ノード1: '<{$node1->nodeName}>'" . PHP_EOL;
45    echo "ノード2: '<{$node2->nodeName}>'" . PHP_EOL;
46    echo "比較結果 (生の数値): " . $position . PHP_EOL;
47
48    // ビット演算子 `&` を使って、返された数値に `DOCUMENT_POSITION_CONTAINS` のビットが
49    // 含まれているか（セットされているか）をチェックします。
50    // この定数と等しい場合、ノード1がノード2を含んでいます。
51    if (($position & Dom_XMLDocument_Simulated::DOCUMENT_POSITION_CONTAINS) === Dom_XMLDocument_Simulated::DOCUMENT_POSITION_CONTAINS) {
52        echo "判定: ノード1 ('<{$node1->nodeName}>') はノード2 ('<{$node2->nodeName}>') を含んでいます。" . PHP_EOL;
53    } else {
54        echo "判定: ノード1 ('<{$node1->nodeName}>') はノード2 ('<{$node2->nodeName}>') を含んでいません。" . PHP_EOL;
55    }
56    echo PHP_EOL;
57}
58
59// --- 以下、サンプルコードの実行部分 ---
60
61// 1. 新しいDOMドキュメントを作成します
62$dom = new DOMDocument('1.0', 'UTF-8');
63$dom->formatOutput = true; // 出力を見やすくするための設定
64
65// 2. DOMツリーを構築します
66$root = $dom->createElement('root');
67$dom->appendChild($root); // <root> をドキュメントに追加
68
69$parent = $dom->createElement('parent');
70$root->appendChild($parent); // <root> の子として <parent> を追加
71
72$child = $dom->createElement('child');
73$parent->appendChild($child); // <parent> の子として <child> を追加
74
75$sibling = $dom->createElement('sibling');
76$root->appendChild($sibling); // <root> の子として <sibling> を追加（<parent> とは兄弟）
77
78echo "--- 構築されたDOMツリー ---" . PHP_EOL;
79echo $dom->saveXML() . PHP_EOL; // 完成したXMLを出力
80
81// 3. 様々なノードの組み合わせで比較関数を実行します
82
83// ケース1: 親ノードが子ノードを含んでいる場合
84//   `parent` ノードは `child` ノードを含んでいます。
85demonstrateDocumentPositionContains($parent, $child);
86
87// ケース2: 子ノードが親ノードを含んでいるか（逆の関係）
88//   `child` ノードは `parent` ノードを含んでいません。
89//   この場合、`DOCUMENT_POSITION_CONTAINED_BY` のビットがセットされますが、`DOCUMENT_POSITION_CONTAINS` はセットされません。
90demonstrateDocumentPositionContains($child, $parent);
91
92// ケース3: 祖先ノードが子孫ノードを含んでいる場合
93//   `root` ノードは `parent` ノードを含んでいます。
94demonstrateDocumentPositionContains($root, $parent);
95
96// ケース4: 祖先ノードが別の直接の子孫を含んでいる場合
97//   `root` ノードは `sibling` ノードを含んでいます。
98demonstrateDocumentPositionContains($root, $sibling);
99
100// ケース5: 兄弟ノードが別の兄弟ノードを含んでいるか
101//   `parent` ノードは `sibling` ノードを含んでいません。
102//   これらは互いに異なるツリーブランチにあるため、「切断された」関係と見なされます。
103demonstrateDocumentPositionContains($parent, $sibling);
104
105// ケース6: 同じノードを比較した場合
106//   DOM仕様では、ノードは自身を含んでいるとは見なされません。
107demonstrateDocumentPositionContains($parent, $parent);

このサンプルコードは、PHPのDOM（Document Object Model）拡張機能を使って、XMLやHTMLドキュメント内で「あるノードが別のノードを含んでいるか」を判定する方法を初心者向けに説明しています。中心となるのは、DOCUMENT_POSITION_CONTAINSという定数です。この定数は、ノード間の位置関係を示すビットマスク値の一つで、具体的には「基準となるノード（$node1）が、比較対象のノード（$node2）を直接的または間接的に含んでいる」という状態を表すために使用されます。

demonstrateDocumentPositionContains関数では、まずDOMNode::compareDocumentPosition()メソッドを使って二つのDOMノードの相対的な位置関係を数値として取得します。このメソッドは、複数の位置関係を示す情報がビットとして組み合わされた数値を返します。次に、取得した数値とDom_XMLDocument_Simulated::DOCUMENT_POSITION_CONTAINS定数をビット演算子&で比較します。もし比較結果がこの定数と一致する場合、基準ノードが比較ノードを含んでいると判断できます。

この関数は引数として二つのDOMノード（$node1, $node2）を受け取ります。$node1が基準、$node2が比較対象となります。関数自体は戻り値を持ちませんが、判定結果を画面に出力します。例えば、親ノードが子ノードを含んでいる場合や、祖先ノードが子孫ノードを含んでいる場合などに、この定数を用いて適切に判断できることをサンプルコードの実行部分で具体的に示しています。