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

Copy
1<?php
2
3/**
4 * Dom\XMLDocument::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、XML ドキュメント内の異なるノード間の位置関係を比較し、
7 * その結果をシステムエンジニアを目指す初心者にも分かりやすいように説明します。
8 *
9 * PHP の推奨コーディングスタイルに従い、PHPDoc コメントを適切に付与することで、
10 * phpdocumentor などのツールでドキュメントを生成しやすくなっています。
11 * また、単体で動作可能なコードとして、現代の PHP 開発で一般的な構成を示します。
12 *
13 * @return void
14 */
15function compareDocumentPositionsExample(): void
16{
17    // 比較対象となるXML文字列
18    $xmlString = <<<XML
19<?xml version="1.0" encoding="UTF-8"?>
20<root>
21    <parent id="p1">
22        <child1 id="c1">テキスト1</child1>
23        <child2 id="c2">
24            <grandchild id="gc1">テキスト2</grandchild>
25        </child2>
26    </parent>
27    <sibling id="s1">テキスト3</sibling>
28</root>
29XML;
30
31    try {
32        // Dom\XMLDocument オブジェクトを作成し、XMLをロード
33        // PHP 8ではDom\XMLDocumentが利用可能です。
34        $document = new Dom\XMLDocument();
35        $document->loadXML($xmlString);
36
37        // XPathを使ってノードを取得
38        // Dom\Document::getElementById は DTD/スキーマの定義がないと動作しない場合があるため、
39        // XPath の使用がより確実なノード取得方法です。
40        $xpath = new Dom\XPath($document);
41
42        // 比較対象となるノードを取得
43        // XPathクエリの結果は DomNodeList で返されるため、item(0) で最初のノードを取得します。
44        $parent1Node = $xpath->query('//parent[@id="p1"]')->item(0); // <parent id="p1">
45        $child1Node = $xpath->query('//child1[@id="c1"]')->item(0); // <child1 id="c1">
46        $grandchild1Node = $xpath->query('//grandchild[@id="gc1"]')->item(0); // <grandchild id="gc1">
47        $sibling1Node = $xpath->query('//sibling[@id="s1"]')->item(0); // <sibling id="s1">
48
49        // 異なるドキュメントのノードをシミュレートするため、新しいドキュメントを作成します。
50        $tempDoc = new Dom\XMLDocument();
51        $tempDoc->loadXML('<other_root><other_node/></other_root>');
52        $otherNode = $tempDoc->documentElement->firstChild; // <other_node>
53
54        // 必要なノードが全て取得できたか確認
55        if (!$parent1Node || !$child1Node || !$grandchild1Node || !$sibling1Node || !$otherNode) {
56            echo "エラー: 必要なノードの一部が見つかりませんでした。XML構造またはXPathクエリを確認してください。\n";
57            return;
58        }
59
60        echo "--- Dom\\XMLDocument::compareDocumentPosition メソッドの例 ---\n\n";
61
62        // 例1: 親と子の関係の比較
63        echo "親(" . $parent1Node->nodeName . ")と子(" . $child1Node->nodeName . ")の比較:\n";
64        compareAndExplain($parent1Node, $child1Node);
65        echo "\n";
66
67        echo "子(" . $child1Node->nodeName . ")と親(" . $parent1Node->nodeName . ")の比較 (逆方向):\n";
68        compareAndExplain($child1Node, $parent1Node);
69        echo "\n";
70
71        // 例2: 兄弟の関係の比較
72        echo "子(" . $child1Node->nodeName . ")と兄弟(" . $sibling1Node->nodeName . ")の比較:\n";
73        compareAndExplain($child1Node, $sibling1Node);
74        echo "\n";
75
76        echo "兄弟(" . $sibling1Node->nodeName . ")と子(" . $child1Node->nodeName . ")の比較 (逆方向):\n";
77        compareAndExplain($sibling1Node, $child1Node);
78        echo "\n";
79
80        // 例3: 自身との比較 (結果は常に0)
81        echo "自身(" . $child1Node->nodeName . ")との比較:\n";
82        compareAndExplain($child1Node, $child1Node);
83        echo "\n";
84
85        // 例4: 祖先と子孫の関係の比較
86        echo "祖先(" . $parent1Node->nodeName . ")と孫(" . $grandchild1Node->nodeName . ")の比較:\n";
87        compareAndExplain($parent1Node, $grandchild1Node);
88        echo "\n";
89
90        echo "孫(" . $grandchild1Node->nodeName . ")と祖先(" . $parent1Node->nodeName . ")の比較:\n";
91        compareAndExplain($grandchild1Node, $parent1Node);
92        echo "\n";
93
94        // 例5: 異なるドキュメントのノードとの比較 (Disconnected)
95        echo "異なるドキュメントのノード('other_node')との比較:\n";
96        compareAndExplain($child1Node, $otherNode);
97        echo "\n";
98
99    } catch (Throwable $e) {
100        // エラーハンドリング: XMLパースエラーなどが発生した場合にキャッチします
101        error_log("エラーが発生しました: " . $e->getMessage());
102        echo "エラーが発生しました: " . $e->getMessage() . "\n";
103    }
104}
105
106/**
107 * 2つのノードを比較し、その結果を分かりやすい文字列で説明するヘルパー関数。
108 * compareDocumentPosition メソッドの戻り値（ビットフラグ）を解析して出力します。
109 *
110 * @param Dom\Node $nodeA 比較する最初のノード
111 * @param Dom\Node $nodeB 比較する2番目のノード
112 * @return void
113 */
114function compareAndExplain(Dom\Node $nodeA, Dom\Node $nodeB): void
115{
116    $result = $nodeA->compareDocumentPosition($nodeB);
117
118    echo "  ノードA ('" . $nodeA->nodeName . "') と ノードB ('" . $nodeB->nodeName . "') の比較結果: " . $result . " (ビットフラグ)\n";
119    echo "  - ";
120
121    $descriptions = [];
122
123    // 結果が0の場合は、ノードAとノードBが同じノードであることを示します。
124    if ($result === 0) {
125        $descriptions[] = "両ノードは同じノードです。";
126    } else {
127        // 結果のビットフラグを解析し、説明を追加
128        if ($result & Dom\Node::DOCUMENT_POSITION_DISCONNECTED) {
129            $descriptions[] = "ノードは異なるドキュメントに属しているか、ツリー内で直接的な関係がありません。";
130        }
131
132        // ノードが同じドキュメント内にある場合の関係を判断します。
133        // CONTAINS と CONTAINED_BY は排他的です。
134        if ($result & Dom\Node::DOCUMENT_POSITION_CONTAINS) {
135            $descriptions[] = "ノードAはノードBを含んでいます (ノードBはノードAの子孫)。";
136        } elseif ($result & Dom\Node::DOCUMENT_POSITION_CONTAINED_BY) {
137            $descriptions[] = "ノードAはノードBに含まれています (ノードAはノードBの子孫)。";
138        }
139
140        // PRECEDING と FOLLOWING は排他的です。
141        if ($result & Dom\Node::DOCUMENT_POSITION_PRECEDING) {
142            $descriptions[] = "ノードAはノードBのソースコード上の前に現れます。";
143        } elseif ($result & Dom\Node::DOCUMENT_POSITION_FOLLOWING) {
144            $descriptions[] = "ノードAはノードBのソースコード上の後に現れます。";
145        }
146
147        // 実装依存のフラグは他の関係と併存する可能性があります。
148        if ($result & Dom\Node::DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
149            $descriptions[] = "実装固有の動作が含まれます (特定のDOM実装に依存する可能性あり)。";
150        }
151    }
152
153    echo implode("\n  - ", $descriptions) . "\n";
154}
155
156// スクリプトが直接実行された場合に、メインのサンプル関数を呼び出します。
157// これはComposerベースのプロジェクトでコマンドラインスクリプトとして実行する際によく見られるパターンです。
158if (php_sapi_name() === 'cli') {
159    compareDocumentPositionsExample();
160}

Dom\XMLDocument::compareDocumentPositionメソッドは、PHPでXMLドキュメント内の二つのノード間の位置関係を比較する際に利用されます。引数$otherには比較対象となるDom\Nodeオブジェクトを指定し、メソッドを呼び出した元のノードとの相対的な位置を判断します。

戻り値は整数値で、これは複数の位置関係情報を組み合わせた「ビットフラグ」として表現されます。ノードが同じか、一方のノードがもう一方を含むか、含まれるか、ソースコード上で前に現れるか後に現れるか、または異なるドキュメントに属しているかといった情報がこの単一の整数値に格納されます。

サンプルコードでは、まずXMLデータからDom\XMLDocumentを作成し、XPathを用いて様々な関係のノード（親、子、兄弟など）を取得しています。これらのノードをcompareDocumentPositionメソッドで比較することで、親ノードが子ノードを「含む」関係や、兄弟ノード間のソースコード上の「前」や「後」の関係がビットフラグとして得られます。また、異なるドキュメントのノードと比較した場合は、「接続されていない」関係が示されます。このように、XMLツリー構造におけるノードの相対的な位置をプログラムで正確に把握し、処理に役立てることが可能です。このコードはphpdocumentorに対応したコメントや、Composerを用いた現代的なPHP開発の構成を参考としています。

Copy
1<?php
2
3/**
4 * Dom\XMLDocument::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、2つのDOMノード間の相対的な位置関係を比較し、その結果を出力します。
7 * PHPDocコメントは、phpdocumentor ツールによって解析され、
8 * 関数の説明、引数、戻り値、および関連情報がドキュメントとして自動生成されます。
9 * これにより、コードの可読性とメンテナンス性が向上します。
10 *
11 * @param string $xmlString 比較に使用するXMLドキュメントの文字列。
12 * @return void 結果を標準出力に出力します。
13 */
14function demonstrateDocumentPositionComparison(string $xmlString): void
15{
16    // 1. 新しいDom\XMLDocumentインスタンスを作成します。
17    $document = new Dom\XMLDocument();
18
19    // 2. XML文字列をロードします。エラーが発生した場合は処理を終了します。
20    if (!$document->loadXML($xmlString)) {
21        echo "エラー: XMLのロードに失敗しました。\n";
22        return;
23    }
24
25    // 3. 比較対象となるノードを取得します。
26    // 例として、ルート要素、最初の子要素、2番目の子要素、孫要素を取得します。
27    $rootElement = $document->getElementsByTagName('bookstore')->item(0);
28    $firstBook = $document->getElementsByTagName('book')->item(0);
29    $secondBook = $document->getElementsByTagName('book')->item(1);
30    $titleOfFirstBook = $document->getElementsByTagName('title')->item(0);
31
32    // 必要なノードが取得できなかった場合はエラーメッセージを表示して終了します。
33    if (!$rootElement || !$firstBook || !$secondBook || !$titleOfFirstBook) {
34        echo "エラー: 必要なXML要素が見つかりませんでした。\n";
35        return;
36    }
37
38    echo "--- Dom\XMLDocument::compareDocumentPosition の使用例 ---\n";
39
40    // ノード比較を実行し、結果を整形して表示するためのヘルパー関数です。
41    $compareAndDisplay = function (Dom\Node $nodeA, Dom\Node $nodeB, string $labelA, string $labelB): void {
42        echo "\n比較: '{$labelA}' と '{$labelB}'\n";
43
44        // compareDocumentPosition メソッドを呼び出し、2つのノード間の位置関係を取得します。
45        $position = $nodeA->compareDocumentPosition($nodeB);
46
47        // 戻り値はビットマスクであり、複数の状態を示すフラグの組み合わせです。
48        echo "  生の結果 (ビットマスク): " . sprintf("0x%02X", $position) . "\n";
49        echo "  解釈された結果:\n";
50
51        if ($position === 0) {
52            echo "    - 両ノードは同じです。\n";
53        }
54        if (($position & Dom\XMLDocument::DOM_DOCUMENT_POSITION_DISCONNECTED) > 0) {
55            echo "    - DISCONNECTED: 両ノードは同じドキュメントに属していますが、ツリー内で接続されていません (例: ドキュメントフラグメント内のノード)。\n";
56        }
57        if (($position & Dom\XMLDocument::DOM_DOCUMENT_POSITION_PRECEDING) > 0) {
58            echo "    - PRECEDING: '{$labelA}' は '{$labelB}' の前にあります。\n";
59        }
60        if (($position & Dom\XMLDocument::DOM_DOCUMENT_POSITION_FOLLOWING) > 0) {
61            echo "    - FOLLOWING: '{$labelA}' は '{$labelB}' の後にあります。\n";
62        }
63        if (($position & Dom\XMLDocument::DOM_DOCUMENT_POSITION_CONTAINS) > 0) {
64            echo "    - CONTAINS: '{$labelA}' は '{$labelB}' を含んでいます (祖先ノード)。\n";
65        }
66        if (($position & Dom\XMLDocument::DOM_DOCUMENT_POSITION_CONTAINED_BY) > 0) {
67            echo "    - CONTAINED_BY: '{$labelA}' は '{$labelB}' に含まれています (子孫ノード)。\n";
68        }
69        // DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC は実装固有のフラグであり、通常は無視できます。
70    };
71
72    // 異なるノードペアで比較を実行し、結果を表示します。
73    $compareAndDisplay($rootElement, $firstBook, 'bookstore (ルート)', '最初のbook (子)');
74    $compareAndDisplay($firstBook, $rootElement, '最初のbook (子)', 'bookstore (ルート)');
75
76    $compareAndDisplay($firstBook, $secondBook, '最初のbook (兄弟)', '2番目のbook (兄弟)');
77    $compareAndDisplay($secondBook, $firstBook, '2番目のbook (兄弟)', '最初のbook (兄弟)');
78
79    $compareAndDisplay($rootElement, $titleOfFirstBook, 'bookstore (祖先)', '最初のbookのtitle (子孫)');
80    $compareAndDisplay($titleOfFirstBook, $rootElement, '最初のbookのtitle (子孫)', 'bookstore (祖先)');
81
82    $compareAndDisplay($firstBook, $titleOfFirstBook, '最初のbook (親)', '最初のbookのtitle (子)');
83    $compareAndDisplay($titleOfFirstBook, $firstBook, '最初のbookのtitle (子)', '最初のbook (親)');
84
85    // 同じノード間の比較
86    $compareAndDisplay($rootElement, $rootElement, 'bookstore', 'bookstore (自身)');
87
88    echo "\n--- 比較終了 ---\n";
89}
90
91// 比較に使用するサンプルXMLデータです。
92$sampleXml = <<<XML
93<?xml version="1.0" encoding="UTF-8"?>
94<bookstore>
95    <book category="cooking">
96        <title lang="en">Everyday Italian</title>
97        <author>Giada De Laurentiis</author>
98        <year>2005</year>
99        <price>30.00</price>
100    </book>
101    <book category="fiction">
102        <title lang="en">The Lord of the Rings</title>
103        <author>J.R.R. Tolkien</author>
104        <year>1954</year>
105        <price>25.00</price>
106    </book>
107</bookstore>
108XML;
109
110// 関数を呼び出し、サンプルXMLデータを使ってDOMノードの位置関係を比較します。
111demonstrateDocumentPositionComparison($sampleXml);

PHP 8のDom\XMLDocument::compareDocumentPositionメソッドは、XMLドキュメント内で指定された2つのDOMノードがどのような位置関係にあるかを比較するために利用されます。引数$otherには比較対象となるもう一方のDom\Nodeオブジェクトを指定します。このメソッドは整数値を返しますが、これは単一の状態を示すものではなく、複数の情報が組み合わされた「ビットマスク」と呼ばれる形式で結果を提供します。

戻り値の整数値は、例えば、両ノードが同じである場合は0を返し、そうでなければDOM_DOCUMENT_POSITION_DISCONNECTED（同じドキュメントだがツリー内で接続なし）、DOM_DOCUMENT_POSITION_PRECEDING（引数のノードより前にある）、DOM_DOCUMENT_POSITION_FOLLOWING（引数のノードより後にある）、DOM_DOCUMENT_POSITION_CONTAINS（引数のノードを含んでいる）、DOM_DOCUMENT_POSITION_CONTAINED_BY（引数のノードに含まれている）といった状態の組み合わせを表現します。

提供されたサンプルコードでは、まずXML文字列をDom\XMLDocumentオブジェクトとして読み込み、その中から複数のDOMノード（ルート要素、子要素、兄弟要素など）を取得しています。その後、これらの異なるノードペアに対してcompareDocumentPositionメソッドを繰り返し呼び出し、それぞれのノード間の相対的な位置関係がビットマスクとしてどのように返され、それが各定数によってどのように解釈されるかを具体的に示しています。これにより、DOMツリー構造におけるノードの親子関係や順序を正確に判断する際に、このメソッドがどのように機能するのかを理解できます。