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

Copy
1<?php
2
3/**
4 * Dom\Attr::compareDocumentPosition メソッドの使用方法をデモンストレーションします。
5 *
6 * このメソッドは、2つのノード (Dom\Attr インスタンスと別の Dom\Node インスタンス) の
7 * ドキュメント内での位置関係を比較し、ビットマスクとして結果を返します。
8 *
9 * 返されるビットマスクは、以下の定数の組み合わせで構成されます。
10 * 結果を解釈するにはビット演算子 (例: `&`) を使用します。
11 *
12 * - DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): 2つのノードは接続されていません (異なるドキュメントに属する、またはDOMツリーに未接続)。
13 * - DOM_DOCUMENT_POSITION_PRECEDING (0x02): 比較対象ノードが現在のノードより前に来る。
14 * - DOM_DOCUMENT_POSITION_FOLLOWING (0x04): 比較対象ノードが現在のノードより後に来る。
15 * - DOM_DOCUMENT_POSITION_CONTAINS (0x08): 現在のノードが比較対象ノードを含んでいる (現在のノードが比較対象ノードの親である)。
16 * - DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): 現在のノードが比較対象ノードに含まれている (現在のノードが比較対象ノードの子である)。
17 * - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装固有の比較結果。
18 *
19 * phpdocumentor互換のPHPDocコメントと、現代的なPHPのコーディングスタイルに準拠しています。
20 * Composerプロジェクトでは、通常 `require __DIR__ . '/vendor/autoload.php';`
21 * を最初に記述し、名前空間やオートローディングを使用しますが、このサンプルはPHPコア機能のみで動作します。
22 *
23 * @return void
24 */
25function demonstrateDomAttrComparison(): void
26{
27    // 1. Dom\Document を作成し、整形出力を有効にする
28    $document = new Dom\Document();
29    $document->formatOutput = true;
30
31    // 2. 要素と属性を作成し、シンプルなDOMツリーを構築
32    // 構築されるDOM構造:
33    // <root id="root-id">
34    //   <child1 name="child1-name">
35    //     <grandchild class="grandchild-class"/>
36    //   </child1>
37    //   <child2 data-value="child2-value"/>
38    // </root>
39
40    $rootElement = $document->createElement('root');
41    $rootAttr = $document->createAttribute('id');
42    $rootAttr->value = 'root-id';
43    $rootElement->appendChild($rootAttr); // 属性を要素に追加
44    $document->appendChild($rootElement); // ルート要素をドキュメントに追加
45
46    $child1Element = $document->createElement('child1');
47    $child1Attr = $document->createAttribute('name');
48    $child1Attr->value = 'child1-name';
49    $child1Element->appendChild($child1Attr);
50    $rootElement->appendChild($child1Element); // child1をrootの子として追加
51
52    $grandchildElement = $document->createElement('grandchild');
53    $grandchildAttr = $document->createAttribute('class');
54    $grandchildAttr->value = 'grandchild-class';
55    $grandchildElement->appendChild($grandchildAttr);
56    $child1Element->appendChild($grandchildElement); // grandchildをchild1の子として追加
57
58    $child2Element = $document->createElement('child2');
59    $child2Attr = $document->createAttribute('data-value');
60    $child2Attr->value = 'child2-value';
61    $child2Element->appendChild($child2Attr);
62    $rootElement->appendChild($child2Element); // child2をrootの子として追加 (child1の後)
63
64    echo "--- 構築されたDOMツリー ---\n";
65    echo $document->saveXML() . "\n";
66    echo "--------------------------\n\n";
67
68    echo "--- Dom\\Attr::compareDocumentPosition のデモンストレーション ---\n\n";
69
70    /**
71     * 2つのノードを比較し、結果を詳細に表示するヘルパー関数。
72     *
73     * @param Dom\Attr $nodeA 比較の基準となる属性ノード。
74     * @param Dom\Node $nodeB 比較対象となるノード。Dom\Attr だけでなく Dom\Element なども可。
75     * @param string $descriptionA nodeAの説明。
76     * @param string $descriptionB nodeBの説明。
77     * @return void
78     */
79    $compareAndDescribe = function (Dom\Attr $nodeA, Dom\Node $nodeB, string $descriptionA, string $descriptionB): void {
80        $result = $nodeA->compareDocumentPosition($nodeB);
81
82        echo "比較: '{$descriptionA}' と '{$descriptionB}'\n";
83        echo "  結果 (ビットマスク): " . sprintf("0x%02X", $result) . " (16進数)\n";
84        echo "  解釈:\n";
85
86        if ($result === 0) {
87            echo "  - 両ノードは同じです。\n";
88        }
89        if (($result & DOM_DOCUMENT_POSITION_DISCONNECTED) === DOM_DOCUMENT_POSITION_DISCONNECTED) {
90            echo "  - 両ノードは接続されていません (例: 異なるドキュメントに属する、またはツリーにまだ追加されていない)。\n";
91        }
92        if (($result & DOM_DOCUMENT_POSITION_PRECEDING) === DOM_DOCUMENT_POSITION_PRECEDING) {
93            echo "  - '{$descriptionA}' は '{$descriptionB}' より**ドキュメント内で前に**あります。\n";
94        }
95        if (($result & DOM_DOCUMENT_POSITION_FOLLOWING) === DOM_DOCUMENT_POSITION_FOLLOWING) {
96            echo "  - '{$descriptionA}' は '{$descriptionB}' より**ドキュメント内で後に**あります。\n";
97        }
98        if (($result & DOM_DOCUMENT_POSITION_CONTAINS) === DOM_DOCUMENT_POSITION_CONTAINS) {
99            echo "  - '{$descriptionA}' は '{$descriptionB}' を**含んでいます** (つまり、{$descriptionA}は{$descriptionB}の祖先です)。\n";
100        }
101        if (($result & DOM_DOCUMENT_POSITION_CONTAINED_BY) === DOM_DOCUMENT_POSITION_CONTAINED_BY) {
102            echo "  - '{$descriptionA}' は '{$descriptionB}' に**含まれています** (つまり、{$descriptionA}は{$descriptionB}の子孫です)。\n";
103        }
104        if (($result & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) === DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
105            echo "  - 実装固有の比較結果です。\n";
106        }
107        echo "\n";
108    };
109
110    // --- 様々な比較例 ---
111
112    // 例1: 基準ノードが比較対象ノードの「前」かつ「親」の属性
113    // $rootAttr は $child1Attr の要素 ($child1Element) の親要素 ($rootElement) の属性です。
114    $compareAndDescribe(
115        $rootAttr,
116        $child1Attr,
117        "ルート要素のID属性 ('root-id')",
118        "子要素1のNAME属性 ('child1-name')"
119    );
120
121    // 例2: 基準ノードが比較対象ノードの「後」かつ「子」の属性
122    // 例1の逆パターンです。
123    $compareAndDescribe(
124        $child1Attr,
125        $rootAttr,
126        "子要素1のNAME属性 ('child1-name')",
127        "ルート要素のID属性 ('root-id')"
128    );
129
130    // 例3: 基準ノードが比較対象ノードの「前」かつ「親」の属性 (更に深い階層)
131    $compareAndDescribe(
132        $child1Attr,
133        $grandchildAttr,
134        "子要素1のNAME属性 ('child1-name')",
135        "孫要素のCLASS属性 ('grandchild-class')"
136    );
137
138    // 例4: 基準ノードが比較対象ノードの「後」かつ「子」の属性 (更に深い階層)
139    $compareAndDescribe(
140        $grandchildAttr,
141        $child1Attr,
142        "孫要素のCLASS属性 ('grandchild-class')",
143        "子要素1のNAME属性 ('child1-name')"
144    );
145
146    // 例5: 同じ親を持つ異なる要素の属性（前後の関係のみ）
147    // $child1Attr は $child2Attr よりDOMツリーで先に位置します。
148    $compareAndDescribe(
149        $child1Attr,
150        $child2Attr,
151        "子要素1のNAME属性 ('child1-name')",
152        "子要素2のDATA属性 ('child2-value')"
153    );
154
155    // 例6: 例5の逆パターン
156    $compareAndDescribe(
157        $child2Attr,
158        $child1Attr,
159        "子要素2のDATA属性 ('child2-value')",
160        "子要素1のNAME属性 ('child1-name')"
161    );
162
163    // 例7: 自分自身との比較 (結果は 0: 同じノード)
164    $compareAndDescribe(
165        $rootAttr,
166        $rootAttr,
167        "ルート要素のID属性 ('root-id')",
168        "ルート要素のID属性 ('root-id') (同じノード)"
169    );
170
171    // 例8: Dom\Attr 以外の Dom\Node (例: Dom\Element) との比較
172    // $rootAttr は $rootElement に含まれます (属性は要素の子ノードとして扱われるため)。
173    $compareAndDescribe(
174        $rootAttr,
175        $rootElement, // Dom\Element は Dom\Node を継承しているので比較可能
176        "ルート要素のID属性 ('root-id')",
177        "ルート要素 (<root>)"
178    );
179
180    // 例9: Dom\Attr 以外の Dom\Node (例: Dom\Element) との比較 (含まれる関係)
181    // $child1Attr は $child1Element に含まれます。
182    $compareAndDescribe(
183        $child1Attr,
184        $child1Element,
185        "子要素1のNAME属性 ('child1-name')",
186        "子要素1 (<child1>)"
187    );
188
189    // 例10: DOMツリーにまだ接続されていないノードとの比較
190    $disconnectedElement = $document->createElement('temp');
191    $disconnectedAttr = $document->createAttribute('temp-attr');
192    $disconnectedAttr->value = 'temp-val';
193    $disconnectedElement->appendChild($disconnectedAttr); // 属性を要素に追加したが、要素はまだドキュメントにない
194
195    $compareAndDescribe(
196        $rootAttr,
197        $disconnectedAttr,
198        "ルート要素のID属性 ('root-id')",
199        "未接続要素のTEMP属性 ('temp-val')"
200    );
201}
202
203// デモンストレーション関数を実行
204demonstrateDomAttrComparison();

PHPのDom\Attr::compareDocumentPositionメソッドは、XMLやHTMLなどのDOMツリー内にある2つのノードの位置関係を比較するための機能です。このメソッドは、Dom\Attrクラスのインスタンスから呼び出され、引数として比較したい別のDom\Nodeインスタンスを受け取ります。

戻り値は整数値で、ビットマスク形式で比較結果を示します。このビットマスクは、ノードがドキュメント内で接続されているか、どちらが前または後に位置するか、あるいは一方のノードがもう一方を含んでいるか（親子関係）といった複数の情報をまとめて表現しています。例えば、DOM_DOCUMENT_POSITION_PRECEDINGは比較対象ノードが現在のノードより前に来ることを、DOM_DOCUMENT_POSITION_CONTAINSは現在のノードが比較対象ノードを含んでいることを意味します。比較結果を正確に解釈するには、ビット演算子&を使用して特定の定数と比較します。

サンプルコードでは、シンプルなDOMツリーを構築し、異なる位置にある属性ノードや要素ノード同士を比較する具体的な例を示しています。親要素の属性と子要素の属性、兄弟要素の属性、あるいは属性自身とそれを保持する要素といった様々なケースで比較を行い、それぞれの結果がビットマスクとしてどのように返され、どのように解釈できるかを詳細に解説しています。このメソッドを使用することで、動的に操作されるDOMツリー内の要素や属性の相対的な位置関係をプログラムで正確に判断することが可能になります。

Copy
1<?php
2
3/**
4 * Dom\Attr::compareDocumentPosition() メソッドの使用例を示します。
5 *
6 * このコードは、2つのDOMノード間の位置関係を比較し、その結果を分かりやすく表示します。
7 * phpDocumentorなどのドキュメント生成ツールは、このようなPHPDocブロックや
8 * 一貫したコーディングスタイルを解析し、効果的なドキュメントを作成します。
9 * そのため、PHPの推奨コーディングスタイルに従うことは、メンテナンス性とドキュメント生成の観点からも重要です。
10 */
11function demonstrateDomAttrComparison(): void
12{
13    // 新しいDOMドキュメントを作成
14    $document = new Dom\Document();
15    $document->formatOutput = true; // 出力時に整形する設定
16
17    // ルート要素を作成し、ドキュメントに追加
18    $rootElement = $document->createElement('root');
19    $document->appendChild($rootElement);
20
21    // 子要素を作成し、ルート要素に追加
22    $childElement = $document->createElement('child');
23    $rootElement->appendChild($childElement);
24
25    // 属性ノードを作成し、子要素に追加
26    $attributeNode = $document->createAttribute('id');
27    $attributeNode->value = 'sample-id';
28    $childElement->setAttributeNode($attributeNode); // 子要素に属性ノードを関連付ける
29
30    echo "--- DOM Structure ---\n";
31    // 現在のDOM構造をXML形式で出力
32    echo $document->saveXML() . "\n";
33    echo "--- Comparison Results ---\n";
34
35    // 比較対象となるノード群を定義
36    $attrToCompare = $attributeNode; // Dom\Attr ノード（compareDocumentPositionの呼び出し元）
37    $parentOfAttr = $childElement;   // $attrToCompare の親要素ノード
38    $ancestorOfAttr = $rootElement;  // $attrToCompare の祖先要素ノード
39    // ドキュメントツリーに接続されていない別のノード
40    $unconnectedNode = $document->createComment('a comment');
41
42    // 複数の比較シナリオを実行し、結果を表示
43    echo "1. Comparing 'attribute' (id='sample-id') with its parent 'child' element:\n";
44    compareNodes($attrToCompare, $parentOfAttr);
45
46    echo "\n2. Comparing 'attribute' (id='sample-id') with its ancestor 'root' element:\n";
47    compareNodes($attrToCompare, $ancestorOfAttr);
48
49    echo "\n3. Comparing 'attribute' (id='sample-id') with an unconnected comment node:\n";
50    compareNodes($attrToCompare, $unconnectedNode);
51
52    echo "\n4. Comparing 'attribute' (id='sample-id') with itself:\n";
53    compareNodes($attrToCompare, $attrToCompare);
54}
55
56/**
57 * 2つのDom\Node間の位置関係を比較し、その結果を詳細に表示するヘルパー関数。
58 *
59 * Dom\Attr::compareDocumentPosition メソッドは、呼び出し元のノード（$nodeA）と
60 * 引数で指定されたノード（$nodeB）との相対的な位置関係を示すビットマスクを整数値で返します。
61 *
62 * @param Dom\Attr $nodeA 比較対象となる最初のノード。Dom\Attr::compareDocumentPositionの呼び出し元であるため、Dom\Attr型である必要があります。
63 * @param Dom\Node $nodeB 比較対象となる2番目のノード。
64 */
65function compareNodes(Dom\Attr $nodeA, Dom\Node $nodeB): void
66{
67    // Dom\Attr::compareDocumentPosition メソッドを呼び出す
68    $position = $nodeA->compareDocumentPosition($nodeB);
69
70    $nodeA_name = getNodeIdentifier($nodeA);
71    $nodeB_name = getNodeIdentifier($nodeB);
72
73    echo "  Position of '{$nodeB_name}' relative to '{$nodeA_name}':\n";
74    echo "  Raw result: " . sprintf("0x%02X", $position) . " (Decimal: " . $position . ")\n";
75
76    // 返されたビットマスクを解析し、それぞれの意味を出力
77    if ($position === 0) {
78        echo "  - The nodes are the same node.\n";
79    }
80
81    if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
82        echo "  - DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): 2つのノードは接続されていません (同じドキュメントにないか、共通の祖先がありません)。\n";
83    }
84    if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
85        echo "  - DOM_DOCUMENT_POSITION_PRECEDING (0x02): \$nodeB はドキュメントツリーにおいて \$nodeA の前に位置します。\n";
86    }
87    if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
88        echo "  - DOM_DOCUMENT_POSITION_FOLLOWING (0x04): \$nodeB はドキュメントツリーにおいて \$nodeA の後に位置します。\n";
89    }
90    if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
91        echo "  - DOM_DOCUMENT_POSITION_CONTAINS (0x08): \$nodeA は \$nodeB を含んでいます (つまり、\$nodeA が \$nodeB の祖先です)。\n";
92    }
93    if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
94        echo "  - DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): \$nodeB は \$nodeA を含んでいます (つまり、\$nodeB が \$nodeA の祖先です)。\n";
95    }
96    if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
97        echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 位置関係は実装に依存します (他のフラグと組み合わせて設定されることがあります)。\n";
98    }
99}
100
101/**
102 * ノードのタイプに応じた識別子（名前や値）を返します。主にデバッグ出力用です。
103 *
104 * @param Dom\Node $node 識別子を取得するDOMノード。
105 * @return string ノードの識別子を表す文字列。
106 */
107function getNodeIdentifier(Dom\Node $node): string
108{
109    if ($node instanceof Dom\Attr) {
110        return "attribute '{$node->name}'='{$node->value}'";
111    } elseif ($node instanceof Dom\Element) {
112        return "element <{$node->tagName}>";
113    } elseif ($node instanceof Dom\Text) {
114        return "text node '{$node->wholeText}'";
115    } elseif ($node instanceof Dom\Comment) {
116        return "comment '<!--{$node->nodeValue}-->'";
117    } elseif ($node instanceof Dom\Document) {
118        return "document";
119    }
120    return $node->nodeName; // その他のノードタイプ
121}
122
123// サンプルコードのエントリポイントとなる関数を実行
124demonstrateDomAttrComparison();

PHPのDom\Attr::compareDocumentPosition()メソッドは、DOM（Document Object Model）ツリーにおける2つのノード間の相対的な位置関係を比較するために使用されます。このメソッドは、呼び出し元のDom\Attrオブジェクト（属性ノード）と、引数で渡されるDom\Node $otherという比較対象のノードの位置関係を整数値で返します。この戻り値はビットマスク形式で、DOM_DOCUMENT_POSITION_DISCONNECTEDやDOM_DOCUMENT_POSITION_FOLLOWINGといった複数の定数の組み合わせによって、ノードが同じドキュメントに属しているか、あるいは一方が他方の前に位置するか、含んでいるかなどの詳細な情報を示します。

サンプルコードでは、最初に新しいDOMドキュメントを作成し、要素と属性ノードを追加して簡単なDOMツリーを構築しています。その後、作成した属性ノードを基準として、その親要素、祖先要素、さらにはドキュメントツリーに接続されていない別のノードなど、複数のノードとの位置関係をcompareDocumentPosition()メソッドで比較しています。メソッドが返す整数値は、別途定義されたヘルパー関数によって解析され、それぞれのビットフラグが持つ意味（例えば、「2つのノードは接続されていません」や「引数のノードは呼び出し元ノードの祖先です」など）が具体的に出力されます。このコードは、phpDocumentorなどのドキュメント生成ツールで利用されるPHPDocブロックの記述例も含んでおり、コードの可読性とメンテナンス性の向上にも役立ちます。