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

Copy
1<?php
2
3/**
4 * DOMNode の位置関係を比較し、その結果を人間が読める形式で出力します。
5 *
6 * この関数は、指定された2つのDOMノード間の位置関係を DOMNode::compareDocumentPosition メソッドを使用して比較します。
7 * 結果はビットマスクとして返されるため、PHPのDOM拡張機能で定義されている定数とビット演算子を用いて、
8 * 詳細な関係性（例: 含まれている、後にあるなど）を判断します。
9 *
10 * このコメントは phpDocumentor が解析できる標準的な形式に従っており、
11 * PHPプロジェクトのドキュメント生成ツールとの互換性を保ちます。
12 *
13 * @param \DOMNode $nodeA 比較対象となる最初のDOMノード。
14 * @param \DOMNode $nodeB 比較対象となる2番目のDOMノード。
15 * @param string $labelA nodeA の説明ラベル（出力用）。
16 * @param string $labelB nodeB の説明ラベル（出力用）。
17 * @return void
18 */
19function compareAndDescribeDomNodes(\DOMNode $nodeA, \DOMNode $nodeB, string $labelA, string $labelB): void
20{
21    // compareDocumentPosition メソッドを呼び出し、2つのノード間の位置関係を取得
22    // 戻り値はビットマスク（整数）です
23    $position = $nodeA->compareDocumentPosition($nodeB);
24
25    echo "--- 比較: '{$labelA}' と '{$labelB}' ---\n";
26
27    // 戻り値が 0 の場合は、両ノードが同じであることを示します
28    if ($position === 0) {
29        echo "  両ノードは同じです。\n";
30        echo "\n";
31        return;
32    }
33
34    // ビット演算子 '&' を使用して、戻り値に含まれる各定数のフラグをチェックします
35    // これにより、複数の関係性が同時に存在する可能性（例: 含まれていて、かつ後にある）を検出できます
36
37    // ノードが互いに接続されていない（異なるDOMツリー、またはDOMツリーから切り離されたノード）
38    if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
39        echo "  両ノードは互いに接続されていません（異なるDOMツリー、またはツリー外）。\n";
40    }
41    // $nodeA が $nodeB よりドキュメント順で前にある
42    if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
43        echo "  '{$labelA}' は '{$labelB}' より前（ドキュメント順）にあります。\n";
44    }
45    // $nodeA が $nodeB よりドキュメント順で後にある
46    if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
47        echo "  '{$labelA}' は '{$labelB}' より後（ドキュメント順）にあります。\n";
48    }
49    // $nodeA が $nodeB を含んでいる（$nodeA が $nodeB の祖先である）
50    if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
51        echo "  '{$labelA}' は '{$labelB}' を含んでいます。\n";
52    }
53    // $nodeA が $nodeB に含まれている（$nodeA が $nodeB の子孫である）
54    if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
55        echo "  '{$labelA}' は '{$labelB}' に含まれています。\n";
56    }
57    // 実装固有の比較結果（一般的なWeb環境ではあまり使用されません）
58    if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
59        echo "  実装固有の比較結果が含まれています。\n";
60    }
61    echo "\n";
62}
63
64// PHP 8 の推奨コーディングスタイルに従い、型宣言や厳密なエラーチェックを含みます。
65// このスクリプトは単体で動作可能であり、Composerで管理されるプロジェクトの一部として
66// 利用されることを想定したコードスタイルに準拠しています。
67
68// DOMDocument オブジェクトを作成し、サンプルXMLをロードします。
69$dom = new DOMDocument('1.0', 'UTF-8');
70// XML文字列をロードします。ここでは簡潔な構造を持つXMLを使用します。
71// Composerプロジェクトでは設定ファイルやデータファイルとしてXMLを扱うことがあります。
72$dom->loadXML(<<<XML
73<project>
74    <modules>
75        <module name="Auth">
76            <component name="Login" />
77            <component name="Logout" />
78        </module>
79        <module name="User">
80            <component name="Profile" />
81        </module>
82    </modules>
83    <config>
84        <setting key="debug" value="true" />
85    </config>
86</project>
87XML);
88
89// XMLドキュメントから比較対象のノードをいくつか取得します。
90// getElementsByTagName は DOMNodeList を返すため、item(0) で最初の要素を取得します。
91$projectNode = $dom->documentElement; // <project>
92$modulesNode = $dom->getElementsByTagName('modules')->item(0); // <modules>
93$authModuleNode = $dom->getElementsByTagName('module')->item(0); // <module name="Auth">
94$loginComponentNode = $dom->getElementsByTagName('component')->item(0); // <component name="Login">
95$userModuleNode = $dom->getElementsByTagName('module')->item(1); // <module name="User">
96$configNode = $dom->getElementsByTagName('config')->item(0); // <config>
97$debugSettingNode = $dom->getElementsByTagName('setting')->item(0); // <setting key="debug">
98
99// ノードが正しく取得できたか確認し、比較処理を実行します。
100if ($projectNode && $modulesNode && $authModuleNode && $loginComponentNode && $userModuleNode && $configNode && $debugSettingNode) {
101    // 1. 親子関係の比較
102    compareAndDescribeDomNodes($projectNode, $modulesNode, 'projectNode', 'modulesNode');
103    compareAndDescribeDomNodes($modulesNode, $loginComponentNode, 'modulesNode', 'loginComponentNode');
104
105    // 2. 兄弟関係の比較
106    compareAndDescribeDomNodes($authModuleNode, $userModuleNode, 'authModuleNode', 'userModuleNode');
107    compareAndDescribeDomNodes($modulesNode, $configNode, 'modulesNode', 'configNode');
108
109    // 3. 祖先と子孫の関係性の逆方向の比較
110    compareAndDescribeDomNodes($loginComponentNode, $authModuleNode, 'loginComponentNode', 'authModuleNode');
111
112    // 4. ドキュメント順での前後関係
113    compareAndDescribeDomNodes($authModuleNode, $debugSettingNode, 'authModuleNode', 'debugSettingNode');
114    compareAndDescribeDomNodes($debugSettingNode, $authModuleNode, 'debugSettingNode', 'authModuleNode');
115
116    // 5. 同じノードの比較 (結果は '両ノードは同じです。' となるはず)
117    compareAndDescribeDomNodes($projectNode, $dom->documentElement, 'projectNode', 'dom->documentElement');
118
119} else {
120    echo "エラー: 比較対象となるノードの取得に失敗しました。\n";
121    echo "サンプルXMLの内容を確認してください。\n";
122}

このサンプルコードは、PHPのDOM拡張機能が提供するDOMNode::compareDocumentPositionメソッドの利用方法を示しています。このメソッドは、二つのDOMNodeオブジェクト間のDOMツリーにおける位置関係を比較するもので、引数には比較対象となるDOMNodeを、戻り値は複数の関係性を表すビットマスク（整数値）として受け取ります。

コード内のcompareAndDescribeDomNodes関数では、この戻り値をビット演算子&とDOM_DOCUMENT_POSITION_xxx定数を用いて解析し、ノードの親子関係や前後関係、あるいは非接続状態などを詳細に出力しています。これにより、DOMツリー内のノードの位置関係を正確に把握する手法を具体的に理解できます。

サンプルスクリプトは、XML文書から取得した複数のDOMNode間で比較を実行することで、メソッドの多様な挙動を示しています。phpDocumentor準拠のコメントやComposerプロジェクトでの利用を想定したコードスタイルに準拠しています。

Copy
1<?php
2
3/**
4 * DOMDocument::compareDocumentPosition メソッドの使用例を示します。
5 *
6 * この関数は、2つのDOMノードの相対的な位置関係を比較し、
7 * システムエンジニアを目指す初心者にも理解しやすいように結果を説明します。
8 * PHPDocコメントの記述例も含まれており、phpDocumentorなどのツールで
9 * ドキュメントを生成する際の「オプション」となる標準的なコメントスタイルを示します。
10 *
11 * @return void
12 */
13function demonstrateCompareDocumentPosition(): void
14{
15    // 比較対象となるHTML構造を持つDOMDocumentオブジェクトを作成
16    $dom = new DOMDocument();
17    // HTMLを読み込みます。エラー抑制演算子@は、HTMLの構造が不完全な場合に
18    // エラーが表示されるのを防ぐためのものです。実運用ではlibxml_use_internal_errors()
19    // などでエラーハンドリングを推奨します。
20    @$dom->loadHTML('
21        <!DOCTYPE html>
22        <html>
23        <body>
24            <div id="container">
25                <p id="first-paragraph">最初の段落です。</p>
26                <p id="second-paragraph">2番目の段落です。</p>
27                <span id="child-span">このスパンはコンテナの子です。</span>
28            </div>
29            <footer id="footer">フッター</footer>
30        </body>
31        </html>
32    ');
33
34    // 比較用のDOMノードを取得します。getElementByIdはIDを持つ要素を返します。
35    // 取得できない場合はnullが返されるため、使用前にnullチェックを行います。
36    $container      = $dom->getElementById('container');
37    $firstParagraph = $dom->getElementById('first-paragraph');
38    $secondParagraph = $dom->getElementById('second-paragraph');
39    $childSpan      = $dom->getElementById('child-span');
40    $footer         = $dom->getElementById('footer');
41
42    /**
43     * DOMNode::compareDocumentPosition の結果コードを人間が読める文字列に変換します。
44     *
45     * @param int $positionCode DOMNode::compareDocumentPosition から返された整数コード。
46     * @return string 位置関係を示す説明文字列。
47     */
48    $interpretPosition = function (int $positionCode): string {
49        $descriptions = [];
50        if ($positionCode === 0) {
51            $descriptions[] = '同じノード';
52        }
53        if ($positionCode & DOMNode::DOCUMENT_POSITION_DISCONNECTED) {
54            $descriptions[] = '関連性がない（異なるサブツリー、または同じドキュメントだが階層関係なし）';
55        }
56        if ($positionCode & DOMNode::DOCUMENT_POSITION_PRECEDING) {
57            $descriptions[] = 'ノードが先行する（比較対象のノードより前にドキュメントに現れる）';
58        }
59        if ($positionCode & DOMNode::DOCUMENT_POSITION_FOLLOWING) {
60            $descriptions[] = 'ノードが後続する（比較対象のノードより後にドキュメントに現れる）';
61        }
62        if ($positionCode & DOMNode::DOCUMENT_POSITION_CONTAINS) {
63            $descriptions[] = 'ノードが比較対象のノードを含む（親ノード）';
64        }
65        if ($positionCode & DOMNode::DOCUMENT_POSITION_CONTAINED_BY) {
66            $descriptions[] = 'ノードが比較対象のノードに含まれる（子ノード）';
67        }
68        // DOCUMENT_POSITION_IMPLEMENTATION_DEFINED は特定のブラウザ実装の詳細に依存するため、
69        // 一般的な説明では割愛することが多いです。
70        return implode(', ', $descriptions);
71    };
72
73    echo "--- DOMDocument::compareDocumentPosition の使用例 ---\n\n";
74
75    // 例 1: 親ノードと子ノードの比較
76    if ($container && $childSpan) {
77        $position = $container->compareDocumentPosition($childSpan);
78        echo "比較: コンテナ と 子スパン (container->compareDocumentPosition(childSpan))\n";
79        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
80        echo "  解釈: " . $interpretPosition($position) . "\n\n";
81    }
82
83    // 例 2: 子ノードと親ノードの比較 (逆方向)
84    if ($childSpan && $container) {
85        $position = $childSpan->compareDocumentPosition($container);
86        echo "比較: 子スパン と コンテナ (childSpan->compareDocumentPosition(container))\n";
87        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
88        echo "  解釈: " . $interpretPosition($position) . "\n\n";
89    }
90
91    // 例 3: 兄弟ノードの比較 (先行)
92    if ($firstParagraph && $secondParagraph) {
93        $position = $firstParagraph->compareDocumentPosition($secondParagraph);
94        echo "比較: 最初の段落 と 2番目の段落 (firstParagraph->compareDocumentPosition(secondParagraph))\n";
95        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
96        echo "  解釈: " . $interpretPosition($position) . "\n\n";
97    }
98
99    // 例 4: 兄弟ノードの比較 (後続)
100    if ($secondParagraph && $firstParagraph) {
101        $position = $secondParagraph->compareDocumentPosition($firstParagraph);
102        echo "比較: 2番目の段落 と 最初の段落 (secondParagraph->compareDocumentPosition(firstParagraph))\n";
103        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
104        echo "  解釈: " . $interpretPosition($position) . "\n\n";
105    }
106
107    // 例 5: 異なるサブツリーだが同じドキュメント内 (関連性なし)
108    if ($container && $footer) {
109        $position = $container->compareDocumentPosition($footer);
110        echo "比較: コンテナ と フッター (container->compareDocumentPosition(footer))\n";
111        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
112        echo "  解釈: " . $interpretPosition($position) . "\n\n";
113    }
114
115    // 例 6: 同じノードの比較
116    if ($firstParagraph) {
117        $position = $firstParagraph->compareDocumentPosition($firstParagraph);
118        echo "比較: 最初の段落 と 最初の段落 (firstParagraph->compareDocumentPosition(firstParagraph))\n";
119        echo "  結果コード: " . $position . " (2進数: " . decbin($position) . ")\n";
120        echo "  解釈: " . $interpretPosition($position) . "\n\n";
121    }
122}
123
124// 関数を実行して結果を表示
125demonstrateCompareDocumentPosition();

PHPのDOMDocument::compareDocumentPositionメソッドは、HTMLやXMLドキュメント内で二つのDOMノードの相対的な位置関係を比較するために使用されます。このメソッドは、指定されたノードがもう一方のノードに対して、ドキュメントツリー上で先行しているか、後続しているか、親であるか、子であるか、あるいは全く関連性がないかといった情報を整数値として返します。

引数には比較したいDOMNodeオブジェクトを一つ渡します。戻り値の整数値は、複数の位置関係を示すビットフラグの組み合わせであり、DOMNode::DOCUMENT_POSITION_PRECEDINGやDOMNode::DOCUMENT_POSITION_CONTAINSといったPHPの定数とビット演算子を用いて、それぞれの意味を個別に解釈できます。

提供されたサンプルコードでは、まずHTML構造を持つDOMDocumentを作成し、そこから特定の要素をノードとして取得しています。これらのノードを用いて、親と子、兄弟、異なる階層のノードといった様々な関係性を実際に比較しています。例えば、親ノードが子ノードと比較された場合、親ノードが子ノードを「含む」という結果コードの一部が返されます。これにより、ドキュメント内のノードがどのような位置関係にあるかをプログラムで判断できるようになります。

また、コードにはphpDocumentor用のコメントが記述されており、これはコードの理解を助け、ドキュメント生成を容易にするための有効な「オプション」です。