【PHP8.x】DOMCdataSection::compareDocumentPosition()メソッドの使い方

Copy
1<?php
2
3/**
4 * このファイルは、PHP の DOM 拡張機能に属する `DOMCdataSection::compareDocumentPosition` メソッドの使用例を示します。
5 * システムエンジニアを目指す初心者の方にも分かりやすいように、XML ドキュメント内のノード間の相対位置を正確かつ簡潔に比較します。
6 *
7 * PHP の推奨コーディングスタイル (PSR-12) に準拠し、phpDocumentor 形式のコメントを含んでいます。
8 * Composer は PHP の依存関係管理ツールですが、この単一ファイルで完結するサンプルでは直接的な利用はありません。
9 */
10
11/**
12 * 2つのDOMノード間の位置関係を比較し、その結果を人間が読める形式で表示します。
13 *
14 * `DOMCdataSection` インスタンスから `compareDocumentPosition` を呼び出し、
15 * 別の `DOMNode` との相対位置を判定します。
16 *
17 * @param DOMCdataSection $cdataNode 比較する基点となるCDATAセクションノード。
18 * @param DOMNode         $otherNode 比較対象となる別のノード。
19 * @return void
20 */
21function demonstrateCompareDocumentPosition(DOMCdataSection $cdataNode, DOMNode $otherNode): void
22{
23    // compareDocumentPosition メソッドを呼び出して、2つのノード間の位置関係を取得します。
24    // 戻り値はビットフラグの組み合わせであり、定数によって意味が定義されています。
25    $position = $cdataNode->compareDocumentPosition($otherNode);
26
27    echo "--- 比較結果 --- \n";
28    echo "ノード1 (CDATA): " . (isset($cdataNode->nodeName) ? $cdataNode->nodeName : '不明なCDATAノード') . "\n";
29    echo "ノード2 (対象): " . (isset($otherNode->nodeName) ? $otherNode->nodeName : '不明なノード') . "\n";
30    echo "位置比較結果 (ビットフラグ): " . $position . "\n";
31    echo "意味: ";
32
33    // 結果のビットフラグを解釈して、それぞれの意味を表示します。
34    // 各定数はビットマスクとして機能し、論理AND演算子 (&) を使って特定のフラグが立っているかを確認します。
35    if ($position === 0) {
36        echo "ノードは同じです。\n";
37        return;
38    }
39
40    $flags = [];
41    if (($position & DOM_DOCUMENT_POSITION_DISCONNECTED) === DOM_DOCUMENT_POSITION_DISCONNECTED) {
42        $flags[] = "切り離されている (Disconnected)";
43    }
44    if (($position & DOM_DOCUMENT_POSITION_PRECEDING) === DOM_DOCUMENT_POSITION_PRECEDING) {
45        $flags[] = "ノード1がノード2より前にある (Preceding)";
46    }
47    if (($position & DOM_DOCUMENT_POSITION_FOLLOWING) === DOM_DOCUMENT_POSITION_FOLLOWING) {
48        $flags[] = "ノード1がノード2より後にある (Following)";
49    }
50    if (($position & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
51        $flags[] = "ノード1がノード2を含んでいる (Contains)";
52    }
53    if (($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
54        $flags[] = "ノード1がノード2に含まれている (Contained By)";
55    }
56    if (($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) === DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
57        $flags[] = "実装固有 (Implementation Specific)";
58    }
59
60    echo implode(", ", $flags) . "\n\n";
61}
62
63// ----------------------------------------------------------------------------------------------------
64// メイン処理: DOMCdataSection インスタンスを作成し、他のノードとの位置を比較する例
65// ----------------------------------------------------------------------------------------------------
66
67// 1. DOMDocument オブジェクトを作成します。XMLのバージョンとエンコーディングを指定します。
68$dom = new DOMDocument('1.0', 'UTF-8');
69$dom->formatOutput = true; // 出力されるXMLを見やすく整形します。
70
71// 2. ルート要素 'data' を作成し、ドキュメントに追加します。
72$root = $dom->createElement('data');
73$dom->appendChild($root);
74
75// 3. 通常のテキストノードを作成し、ルート要素に追加します。
76$textNode = $dom->createTextNode('これは通常のテキストです。');
77$root->appendChild($textNode);
78
79// 4. CDATAセクションノードを作成し、ルート要素に追加します。
80//    `DOMCdataSection` は `DOMNode` の子クラスであり、`compareDocumentPosition` メソッドを継承しています。
81$cdataSection = $dom->createCDATASection('特別な <マークアップ> や &エンティティ; をそのまま保持する');
82$root->appendChild($cdataSection);
83
84// 5. 別の要素 'info' を作成し、ルート要素に追加します。
85$anotherElement = $dom->createElement('info', '追加情報');
86$root->appendChild($anotherElement);
87
88echo "--- 生成されたDOM構造 ---\n";
89echo $dom->saveXML() . "\n";
90
91// ----------------------------------------------------------------------------------------------------
92// 比較例1: CDATAセクションと通常のテキストノードの比較
93// XMLツリーでは、`cdataSection` は `textNode` の後に位置します。
94// ----------------------------------------------------------------------------------------------------
95echo "=== 比較例1: CDATAセクション ($cdataSection->nodeName) と通常のテキストノード ($textNode->nodeName) ===\n";
96demonstrateCompareDocumentPosition($cdataSection, $textNode);
97
98// ----------------------------------------------------------------------------------------------------
99// 比較例2: CDATAセクションと別の要素の比較
100// XMLツリーでは、`cdataSection` は `anotherElement` の前に位置します。
101// ----------------------------------------------------------------------------------------------------
102echo "=== 比較例2: CDATAセクション ($cdataSection->nodeName) と別の要素 ($anotherElement->nodeName) ===\n";
103demonstrateCompareDocumentPosition($cdataSection, $anotherElement);
104
105// ----------------------------------------------------------------------------------------------------
106// 比較例3: CDATAセクションと自身の親ノードの比較
107// `cdataSection` は `root` の子ノードであり、`root` に含まれています。
108// ----------------------------------------------------------------------------------------------------
109echo "=== 比較例3: CDATAセクション ($cdataSection->nodeName) と親ノード ($root->nodeName) ===\n";
110demonstrateCompareDocumentPosition($cdataSection, $root);
111
112// ----------------------------------------------------------------------------------------------------
113// 比較例4: CDATAセクションと自身との比較
114// 同じノードを比較した場合、戻り値は 0 となります。
115// ----------------------------------------------------------------------------------------------------
116echo "=== 比較例4: CDATAセクション ($cdataSection->nodeName) と自身 ($cdataSection->nodeName) ===\n";
117demonstrateCompareDocumentPosition($cdataSection, $cdataSection);
118

PHPのDOMCdataSection::compareDocumentPositionメソッドは、XMLやHTMLドキュメント内で2つのノード間の相対的な位置関係を判定するために使用されます。このメソッドはDOMCdataSectionオブジェクトから呼び出されますが、実際には基底クラスであるDOMNodeから継承された機能です。引数には比較対象となる別のDOMNodeオブジェクトを指定します。

戻り値は整数値で、これは複数の情報を同時に示すビットフラグの組み合わせとして表現されます。例えば、DOM_DOCUMENT_POSITION_PRECEDINGは、呼び出し元のノードが引数のノードよりドキュメントツリー上で前にあることを示し、DOM_DOCUMENT_POSITION_FOLLOWINGは後にあることを意味します。また、DOM_DOCUMENT_POSITION_CONTAINSは呼び出し元のノードが引数のノードを含んでいることを、DOM_DOCUMENT_POSITION_CONTAINED_BYは呼び出し元のノードが引数のノードに含まれていることを示します。ノード間に親子関係がなく、ドキュメントツリー上で独立している場合はDOM_DOCUMENT_POSITION_DISCONNECTEDが設定されます。

これらのビットフラグは、戻り値と対応する定数をビット論理AND演算子（&）で比較することで、個別にその意味を解釈できます。サンプルコードでは、CDATAセクションノードを基準として、ドキュメント内の他のテキストノード、別の要素、自身の親ノード、そして自身との比較を通じて、それぞれの位置関係がどのように判定され、結果が解釈されるかを具体的に示しています。これにより、XMLドキュメントの複雑なツリー構造におけるノードの相対的な位置をプログラムで正確に把握し、適切な処理を実装することが可能になります。

Copy
1<?php
2
3/**
4 * DOMCdataSection::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、DOMツリー内のDOMCdataSectionノードと他のノードの相対的な位置関係を比較し、
7 * その結果を標準出力に出力します。
8 *
9 * システムエンジニアを目指す初心者の方々が、DOMノード間の関係性や
10 * compareDocumentPosition メソッドの戻り値（ビットマスク）を理解するのに役立つように、
11 * 読みやすい形式で結果を説明します。
12 *
13 * また、phpDocumentorのようなツールがPHPコードを適切にドキュメント化できるよう、
14 * PHPDocコメントの推奨される書き方に従っています。
15 *
16 * @return void
17 */
18function demonstrateCdataSectionComparison(): void
19{
20    // 新しいDOMドキュメントを作成します。
21    $dom = new DOMDocument('1.0', 'UTF-8');
22    $dom->formatOutput = true; // 出力を整形するために設定します。
23
24    // ルート要素を作成し、ドキュメントに追加します。
25    $rootElement = $dom->createElement('root');
26    $dom->appendChild($rootElement);
27
28    // DOMCdataSection ノードを作成し、ルート要素に追加します。
29    // このノードが比較の「基準」となるノードです。
30    $cdataNode = $dom->createCDATASection("これは <CDATA> セクションのテストです。特殊文字も含まれます。");
31    $rootElement->appendChild($cdataNode);
32
33    // 比較対象となる様々なタイプのノードを作成し、DOMツリーに追加します。
34
35    // 基準ノードの「前」に配置されるテキストノードです。
36    $textNodeBefore = $dom->createTextNode('これはCDataSectionノードより前のテキストです。');
37    $rootElement->insertBefore($textNodeBefore, $cdataNode); // cdataNodeの前に挿入します。
38
39    // 基準ノードの「後」に配置されるテキストノードです。
40    $textNodeAfter = $dom->createTextNode('これはCDataSectionノードより後のテキストです。');
41    $rootElement->appendChild($textNodeAfter);
42
43    // 別のDOMCdataSectionノードです。（基準ノードの「後」に配置されます）
44    $anotherCdataNode = $dom->createCDATASection("これは別のCDATAセクションです。");
45    $rootElement->appendChild($anotherCdataNode);
46
47    // ドキュメントツリーに属さないノードです。（比較のために用意します）
48    $unattachedNode = $dom->createTextNode('これはドキュメントに属さないノードです。');
49
50    /**
51     * DOMCdataSection::compareDocumentPosition メソッドの結果を人間が読める形式に変換するヘルパー関数。
52     *
53     * DOMCdataSection::compareDocumentPosition は整数値（ビットマスク）を返しますが、
54     * その値は複数のDOM_DOCUMENT_POSITION_定数の組み合わせとして解釈されます。
55     * この関数は、そのビットマスクを分かりやすい文字列に変換します。
56     *
57     * @param int $result DOMCdataSection::compareDocumentPosition から返された整数値。
58     * @return string 結果のビットマスクを説明する文字列。
59     */
60    $decodeComparisonResult = function (int $result): string {
61        $messages = [];
62        if ($result === 0) {
63            return '同じノード'; // 0 はノードが同じであることを示す特別な値です。
64        }
65        if ($result & DOM_DOCUMENT_POSITION_DISCONNECTED) {
66            $messages[] = 'DISCONNECTED (ノードが異なるツリーに存在するか、ツリー内の関係がない)';
67        }
68        if ($result & DOM_DOCUMENT_POSITION_PRECEDING) {
69            $messages[] = 'PRECEDING (比較対象ノードが現在のノードの前に現れる)';
70        }
71        if ($result & DOM_DOCUMENT_POSITION_FOLLOWING) {
72            $messages[] = 'FOLLOWING (比較対象ノードが現在のノードの後に現れる)';
73        }
74        if ($result & DOM_DOCUMENT_POSITION_CONTAINS) {
75            $messages[] = 'CONTAINS (現在のノードが比較対象ノードを含む)';
76        }
77        if ($result & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
78            $messages[] = 'CONTAINED_BY (現在のノードが比較対象ノードに含まれる)';
79        }
80        if ($result & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
81            $messages[] = 'IMPLEMENTATION_SPECIFIC (実装依存の追加情報)';
82        }
83        return empty($messages) ? '不明な状態 (結果コード: ' . $result . ')' : implode(' | ', $messages);
84    };
85
86    echo "--- DOMCdataSection::compareDocumentPosition の使用例 ---\n\n";
87    echo "基準ノード: DOMCdataSection ('" . substr($cdataNode->nodeValue, 0, 30) . "...')\n\n";
88
89    // 1. 自分自身との比較
90    echo "1. 基準ノード自身との比較:\n";
91    // compareDocumentPosition(DOMNode $other) - 比較対象のノードを引数に取ります。
92    $resultSelf = $cdataNode->compareDocumentPosition($cdataNode);
93    echo "   結果 (int): " . $resultSelf . "\n";
94    echo "   意味: " . $decodeComparisonResult($resultSelf) . "\n\n";
95
96    // 2. 基準ノードの前に存在するノードとの比較
97    echo "2. 基準ノードの前に存在するテキストノードとの比較 ('" . substr($textNodeBefore->nodeValue, 0, 30) . "...'):\n";
98    // 基準ノード(cdataNode)から見て、比較対象(textNodeBefore)がどこにあるかを調べます。
99    $resultBefore = $cdataNode->compareDocumentPosition($textNodeBefore);
100    echo "   結果 (int): " . $resultBefore . "\n";
101    echo "   意味: " . $decodeComparisonResult($resultBefore) . "\n\n";
102
103    // 3. 基準ノードの後に存在するノードとの比較
104    echo "3. 基準ノードの後に存在するテキストノードとの比較 ('" . substr($textNodeAfter->nodeValue, 0, 30) . "...'):\n";
105    // 基準ノード(cdataNode)から見て、比較対象(textNodeAfter)がどこにあるかを調べます。
106    $resultAfter = $cdataNode->compareDocumentPosition($textNodeAfter);
107    echo "   結果 (int): " . $resultAfter . "\n";
108    echo "   意味: " . $decodeComparisonResult($resultAfter) . "\n\n";
109
110    // 4. 親要素との比較
111    echo "4. 基準ノードの親要素 ('" . $rootElement->nodeName . "') との比較:\n";
112    // 基準ノード(cdataNode)から見て、比較対象(rootElement)がどこにあるかを調べます。
113    $resultParent = $cdataNode->compareDocumentPosition($rootElement);
114    echo "   結果 (int): " . $resultParent . "\n";
115    echo "   意味: " . $decodeComparisonResult($resultParent) . "\n\n";
116
117    // 5. 別のCDATAノードとの比較 (同じツリー内、基準ノードの後に存在する)
118    echo "5. 基準ノードの後に存在する別のCDataSectionノードとの比較 ('" . substr($anotherCdataNode->nodeValue, 0, 30) . "...'):\n";
119    // 基準ノード(cdataNode)から見て、比較対象(anotherCdataNode)がどこにあるかを調べます。
120    $resultAnotherCdata = $cdataNode->compareDocumentPosition($anotherCdataNode);
121    echo "   結果 (int): " . $resultAnotherCdata . "\n";
122    echo "   意味: " . $decodeComparisonResult($resultAnotherCdata) . "\n\n";
123
124    // 6. ドキュメントツリーに属さないノードとの比較
125    echo "6. ドキュメントに属さないノードとの比較 ('" . substr($unattachedNode->nodeValue, 0, 30) . "...'):\n";
126    // 基準ノード(cdataNode)から見て、比較対象(unattachedNode)がどこにあるかを調べます。
127    $resultUnattached = $cdataNode->compareDocumentPosition($unattachedNode);
128    echo "   結果 (int): " . $resultUnattached . "\n";
129    echo "   意味: " . $decodeComparisonResult($resultUnattached) . "\n\n";
130}
131
132// 関数の実行を開始します。
133demonstrateCdataSectionComparison();

PHP 8のDOMCdataSection::compareDocumentPositionメソッドは、DOMツリー内のDOMCdataSectionノードと、引数で指定されたDOMNode $otherの相対的な位置関係を比較する機能を提供します。このメソッドは整数値を戻り値として返し、その値は複数のビットフラグ（ビットマスク）の組み合わせで、比較対象ノードが基準ノードの「前にある（PRECEDING）」、「後にある（FOLLOWING）」、「含まれる（CONTAINED_BY）」、「含んでいる（CONTAINS）」、「関連がない（DISCONNECTED）」などの状態を示します。

サンプルコードでは、まずDOMDocumentを初期化し、基準となるDOMCdataSectionノードを含むDOMツリーを構築しています。次に、自身、親ノード、兄弟ノード（前後に配置されたテキストノードや別のCDATAセクション）、そしてドキュメントツリーに属さないノードなど、多様なDOMNodeを$other引数としてcompareDocumentPositionメソッドに渡し、それぞれの比較結果を詳しく出力しています。戻り値のビットマスクは、専用のヘルパー関数によって、初心者にも理解しやすいように具体的な意味に変換されて表示されます。この例を通じて、DOMノード間の複雑な位置関係をプログラムでどのように判別できるか、またphpDocumentorなどのツールで活用されるPHPDocコメントの書き方も示されています。